@uniweb/api 0.1.0 → 0.2.1

package/README.md

@@ -1,69 +1,149 @@
 # @uniweb/api
 
-The client for a Uniweb site's own backend — session, records, entities, writes — in the site's
-vocabulary, never in routes. A foundation imports it the way it imports `@uniweb/kit`; it is bundled
-into the foundation and is inert on a site that declares no backend.
+The client a foundation uses to talk to **its site's own backend** — sign-in, the
+site's members, and the content they create.
 
-**Status: early.** The session, sign-in, sign-out, sign-up, password reset and single-entity reads
-are built and pass against a real backend; lists of records, writes, commerce and notifications are
-not here yet. The surface may still move before `1.0`.
+You import it the way you import `@uniweb/kit`. It is bundled into your foundation,
+tree-shaken, and **inert on a site that has no backend**: nothing throws, no request
+leaves, and your components render the version of themselves that does not need one.
 
-## What it will be
+```bash
+npm install @uniweb/api
+```
 
-- **A session.** Who the viewer is, and sign-in, sign-up and sign-out as functions a component
-  calls — never as routes it constructs.
-- **Reads in the site's vocabulary.** Named queries over the site's records, and single entities by
-  id, gated by what the viewer may see.
-- **Writes.** Entity creation and per-item updates, with concurrency tokens, optimistic state and
-  cache invalidation handled for you.
-- **Two entry points.** `@uniweb/api` for the React hooks; `@uniweb/api/client` for the plain
-  functions, with no React import.
+## Is there a backend?
 
-## What it does today
+Ask before you draw. This is a synchronous read of the site's own configuration, not
+a probe — there is nothing to await.
 
-```js
-import { useSession, useSignIn, useEntity, SignedIn, SignedOut } from '@uniweb/api'
+```jsx
+import { isEnabled } from '@uniweb/api'
+
+if (!isEnabled(website)) return <StaticVersion />
+```
+
+⛔ **And when the answer is no, draw nothing** — not a disabled button, and not an
+explanation. A visitor has no stake in which services the site's operator set up, and
+"sign-in is unavailable" reads like a breakage when it is simply a feature this site
+does not have.
+
+## The session
+
+```jsx
+import { useSession, useSignIn, SignedIn, SignedOut } from '@uniweb/api'
+
+function Account() {
+  const { viewer, signOut } = useSession()
+  const { signIn, status, error } = useSignIn()
+
+  return (
+    <>
+      <SignedIn>
+        {viewer.handle} <button onClick={signOut}>Sign out</button>
+      </SignedIn>
+      <SignedOut>
+        <button onClick={() => signIn({ username, password })}>Sign in</button>
+        {error && <span>{error.detail}</span>}
+      </SignedOut>
+    </>
+  )
+}
+```
+
+`viewer` is flat — `viewer.handle`, `viewer.uuid`, `viewer.roles`. Also
+`useSignUp`, `usePasswordReset`, and `completeChallenge` for two-factor sign-in.
+
+## Reading
+
+```jsx
+import { useRecords, useEntity } from '@uniweb/api'
+
+const { status, records, matched, hasMore } = useRecords({ schema: '@/session' })
+```
 
-const { status, viewer, canSignIn, error, signOut, refresh } = useSession()
-// status: 'loading' | 'anonymous' | 'authenticated' — `anonymous` synchronously on
-// a site with no backend. One session per page, however many foundations it loads.
+⭐ **`absent` and an empty `ready` are different answers.** `absent` means there is no
+live source — no backend, or nobody signed in — so render your site's own content.
+`ready` with `records: []` means the backend answered and there is nothing there.
+Showing "nothing yet" for the first case tells a visitor their content is missing
+when it is simply not being asked for.
 
-const { signIn, completeChallenge, challenge, status: signInStatus } = useSignIn()
-// signIn(credentials) posts the object unchanged; a second factor parks in
-// `challenge`, and completeChallenge(code) finishes it.
+`useEntity({ schema, uuid, via })` reads one record. Its `absent` covers both
+not-found and not-permitted, on purpose: render your paywall or sign-in prompt on it
+and never say "deleted".
 
-const lesson = useEntity({ schema: '@/lesson', uuid, via: course.uuid })
-// status: 'loading' | 'ready' | 'absent' | 'error' — `absent` is one word for
-// not-found-and-not-permitted, so render the wall on it and never say "deleted".
+## Writing
 
-<SignedIn fallback={<Wall />}><Roster /></SignedIn>
+```jsx
+import { useEntityWriter } from '@uniweb/api'
+
+const programme = useEntityWriter({ schema: '@/track', uuid: track.uuid })
+
+await programme.create({ title: 'Keynote' }, { section: 'sessions', position: 'last' })
+await programme.update(itemId, { ...item.data, room: 'Hall A' })
+await programme.move(itemId, { after: otherItemId })
+await programme.remove(itemId)
+await programme.batch([...])          // one transaction: all of them, or none
+```
+
+Three things it does for you, and one it deliberately does not:
+
+- **Concurrency is handled.** Every write carries the item's last-seen version and the
+  response updates it. You never touch a token.
+- **`section` is required on `create`.** An entity has several, and a rule declared on
+  one — insert-only, say — does not reach an item that landed in another.
+- **A successful write refreshes what it changed**, so a list you are showing reflects
+  it without a manual reload.
+- ⛔ **A conflict is reported, never retried.** `writer.conflict` is set when someone
+  else changed the item first. A retry would *succeed*, by overwriting a change nobody
+  looked at — so what happens next is your application's decision, and usually it is
+  to tell the person.
+
+⚠️ `update` replaces the item's data whole. Spread what you are not editing.
+
+## A backend on your machine
+
+Building against a live backend is slow and puts a shared database behind your
+experiments. Name a local one in `site.yml`:
+
+```yaml
+api: /_api                 # where the backend answers — the same in production
+$devApi: ./mock/api.js     # what answers it locally; never published
 ```
 
-Outside React the same calls are plain functions from `@uniweb/api/client` — `probeSession`,
-`signIn`, `completeChallenge`, `signOut`, `signUp`, `requestPasswordReset`,
-`confirmPasswordReset`, `readEntity`. Every refusal is an `ApiError` with a `kind` to branch on:
-`auth`, `absent`, `forbidden`, `invalid`, `conflict`, `csrf`, `step-up`, `rate-limited`,
-`unavailable`, `disabled`.
+```js
+// mock/api.js
+import { createMockBackend } from '@uniweb/api/mock'
+
+export default createMockBackend({
+  seed: {
+    accounts: [{ username: 'me', password: 'me', units: ['staff'] }],
+    schemas: { '@/session': { creatable_by: 'unit_members' } },
+    entities: [{ uuid: 't-1', model: '@/track', data: { name: 'Main hall' }, items: [] }],
+  },
+}).fetch
+```
 
-Not yet: lists of records, writes, commerce, notifications.
+`uniweb dev` mounts it at your `api:` address — same origin, so cookies behave as they
+will in production, and your site's configuration is identical either way.
 
-## Testing
+It **enforces** what your schemas declare — who may create entries, and which sections
+are insert-only — so a permission you are relying on fails here rather than in front
+of a user. State is in memory: restart to reset.
 
-`pnpm test` runs the suite against a stubbed `fetch` — this package's own logic. The live suite
-runs the same calls against a real backend and is skipped unless `UNIWEB_API_BASE` names one. For
-the signed-in half, either pass `UNIWEB_API_LOGIN` (the JSON body of a sign-in) or set
-`UNIWEB_API_REGISTER=1` and the suite provisions a throwaway account through the backend's own
-sign-up path. No fake backend ships here.
+There is also a standalone server, for a frontend that is not a Uniweb site:
 
 ```bash
-UNIWEB_API_BASE=http://localhost:8080 UNIWEB_API_REGISTER=1 pnpm test
+npx uniweb-api-mock --port 8787
 ```
 
-## How a site declares its backend
+⛔ **The mock is a fixture of what this package expects, not a model of any real
+backend.** Behaviour it happens to have is evidence about the mock and nothing else.
+
+## Outside React
 
-The address is a site service named `api`, resolved like every other service: the site's own `api:`
-in `site.yml` wins, then the host's `services.api`; absent from both, the site has no backend and the
-package does nothing. A foundation never writes the address.
+`@uniweb/api/client` carries the same operations as plain functions and imports no
+React: `probeSession`, `signIn`, `listEntities`, `readEntity`, `writeItems`,
+`createEntity`, `deleteEntity`.
 
 ## License
 

package/bin/uniweb-api-mock.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * `npx uniweb-api-mock` — the mock backend on a port.
+ *
+ * ⚠️ Prefer mounting `middleware()` in the dev server you already run: the API is
+ * then same-origin with the site, which is what a real deployment looks like. Use
+ * this when the frontend is not a Uniweb site, or when proxying to it.
+ *
+ *   uniweb-api-mock [--port 8787] [--prefix /_api] [--seed ./seed.js]
+ */
+import { createMockBackend } from '../src/mock/index.js'
+import { serve } from '../src/mock/node.js'
+
+const argv = process.argv.slice(2)
+const flag = (name, fallback) => {
+  const at = argv.indexOf(`--${name}`)
+  return at >= 0 && argv[at + 1] ? argv[at + 1] : fallback
+}
+
+const seedPath = flag('seed', null)
+const seed = seedPath ? (await import(new URL(seedPath, `file://${process.cwd()}/`).href)).default : undefined
+
+const mock = createMockBackend({ ...(seed ? { seed } : {}) })
+const server = await serve(mock, { port: Number(flag('port', 8787)), prefix: flag('prefix', '') })
+
+console.log(`uniweb-api-mock listening on ${server.url}`)
+console.log(`  accounts: ${mock.store.accounts.map((a) => a.username).join(', ')}`)
+console.log('  state is in memory — restart to reset')
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    server.close().then(() => process.exit(0))
+  })
+}

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@uniweb/api",
-  "version": "0.1.0",
+  "version": "0.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": {
     ".": "./src/index.js",
-    "./client": "./src/client.js"
+    "./client": "./src/client.js",
+    "./wire": "./src/wire.js",
+    "./mock": "./src/mock/index.js",
+    "./mock/node": "./src/mock/node.js"
   },
   "files": [
-    "src"
+    "src",
+    "bin"
   ],
   "sideEffects": false,
   "keywords": [
@@ -30,7 +34,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.14.1"
+    "@uniweb/core": "^0.15.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"
@@ -42,6 +46,9 @@
     "react-dom": "^19.0.0",
     "vitest": "^4.1.7"
   },
+  "bin": {
+    "uniweb-api-mock": "./bin/uniweb-api-mock.js"
+  },
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest"

package/src/client.js

@@ -15,6 +15,8 @@ import { getUniweb, deriveCacheKey } from '@uniweb/core'
 import { resolveService } from '@uniweb/core/services'
 import { ApiError } from './errors.js'
 import { composeUrl, isCrossOrigin, readBody, UNSAFE } from './http.js'
+import { AUTH, ROUTES, PARAM, FIELD, LIST, OP } from './wire.js'
+import { Ledger } from './ledger.js'
 
 /** The site service this package reads its base from — the only name it owns. */
 export const SERVICE_NAME = 'api'
@@ -87,8 +89,11 @@ export class ApiClient {
     this._listeners = new Set()
     this._pending = null
     this._challenge = null
-    this._keys = new Set()
+    this._keys = new Map()
     this._inflight = new Map()
+    // One ledger per client, which is one per page — the right grain, since it is
+    // keyed by item and an item is the same item whoever is looking at it.
+    this.ledger = new Ledger()
     this._session = this.enabled ? LOADING : ANONYMOUS
     // Stable identity: `useSyncExternalStore` re-subscribes when this changes.
     this.subscribe = this.subscribe.bind(this)
@@ -253,7 +258,7 @@ export class ApiClient {
 
   async _probe() {
     try {
-      const me = await this.request('GET', '/auth/me', { onUnauthorized: 'ignore' })
+      const me = await this.request('GET', AUTH.me, { onUnauthorized: 'ignore' })
       return this._authenticated(me)
     } catch (err) {
       if (err instanceof ApiError && err.status === 401) return this._sessionLost()
@@ -289,7 +294,7 @@ export class ApiClient {
    *   with `completeChallenge(code)`. A refused credential throws (`kind: 'auth'`).
    */
   async signIn(credentials) {
-    const body = await this.request('POST', '/auth/login', { body: credentials, onUnauthorized: 'ignore' })
+    const body = await this.request('POST', AUTH.login, { body: credentials, onUnauthorized: 'ignore' })
     if (body?.status === 'totp_required') {
       this._challenge = body.challenge_token ?? null
       return { ok: false, challenge: { kind: 'totp' } }
@@ -309,7 +314,7 @@ export class ApiClient {
     if (!this._challenge) {
       throw new ApiError({ status: 0, title: 'No Challenge', detail: 'no sign-in challenge is pending', kind: 'invalid' })
     }
-    await this.request('POST', '/auth/login/challenge', {
+    await this.request('POST', AUTH.challenge, {
       body: { challenge_token: this._challenge, code },
       onUnauthorized: 'ignore',
     })
@@ -325,7 +330,7 @@ export class ApiClient {
    */
   async signOut() {
     try {
-      await this.request('POST', '/auth/logout', { onUnauthorized: 'ignore' })
+      await this.request('POST', AUTH.logout, { onUnauthorized: 'ignore' })
     } finally {
       this._sessionLost()
     }
@@ -333,17 +338,17 @@ export class ApiClient {
 
   /** Sign up. `202` semantics: the account is inert until verified. */
   signUp(fields) {
-    return this.request('POST', '/auth/register', { body: fields, onUnauthorized: 'ignore' })
+    return this.request('POST', AUTH.register, { body: fields, onUnauthorized: 'ignore' })
   }
 
   /** Ask for a password reset. The backend answers `202` whether or not the account exists. */
   requestPasswordReset(fields) {
-    return this.request('POST', '/auth/reset/request', { body: fields, onUnauthorized: 'ignore' })
+    return this.request('POST', AUTH.resetRequest, { body: fields, onUnauthorized: 'ignore' })
   }
 
   /** Confirm a password reset with the token the viewer received. */
   confirmPasswordReset(fields) {
-    return this.request('POST', '/auth/reset/confirm', { body: fields, onUnauthorized: 'ignore' })
+    return this.request('POST', AUTH.resetConfirm, { body: fields, onUnauthorized: 'ignore' })
   }
 
   // ── The cache ─────────────────────────────────────────────────────────────
@@ -361,37 +366,79 @@ export class ApiClient {
     return deriveCacheKey({ ...spec, endpoint: `api:${this.viewerId}:${spec.endpoint ?? ''}` })
   }
 
-  /** Note a key this client wrote, so sign-out can remove it. */
-  remember(key) {
-    this._keys.add(key)
+  /**
+   * Note a key this client wrote, so sign-out can remove it — and remember the
+   * SPEC beside it, so a write can drop what it invalidated.
+   *
+   * ⚠️ The spec is kept because a key is a derived hash: nothing can be recovered
+   * from the key itself, so a cache that only holds keys can be cleared entirely
+   * or not at all.
+   *
+   * @param {string} key
+   * @param {object} [spec] - the spec the key was derived from
+   */
+  remember(key, spec) {
+    this._keys.set(key, spec || null)
   }
 
   /** Remove every entry written for the current viewer. */
   forgetViewer() {
     const store = this.website?.dataStore
-    for (const key of this._keys) {
+    for (const key of this._keys.keys()) {
       store?.delete(key)
       this._inflight.delete(key)
     }
     this._keys.clear()
   }
 
+  /**
+   * Drop the cached reads a predicate matches — how a write makes its own effect
+   * visible without every caller hand-rolling it.
+   *
+   * ```js
+   * client.invalidate((spec) => spec.schema === '@/session')
+   * ```
+   *
+   * ⛔ **A key with no remembered spec is never matched, and never swept.** It is
+   * not knowable whether it belongs, and dropping an entry a caller still relies on
+   * to be safe about one it might not is the wrong trade: a stale read is visible
+   * and recoverable, an over-eager sweep is a refetch storm nobody attributes to
+   * this line.
+   *
+   * @param {(spec: object) => boolean} match
+   * @returns {number} how many entries were dropped
+   */
+  invalidate(match) {
+    if (typeof match !== 'function') return 0
+    const store = this.website?.dataStore
+    let dropped = 0
+    for (const [key, spec] of this._keys) {
+      if (!spec || !match(spec)) continue
+      store?.delete(key)
+      this._inflight.delete(key)
+      this._keys.delete(key)
+      dropped += 1
+    }
+    return dropped
+  }
+
   /**
    * Read through the cache: a hit answers at once, a miss runs `run` once for
    * every concurrent caller and writes what it returns.
    *
    * @param {string} key
    * @param {() => Promise<*>} run
+   * @param {object} [spec] - what the key was derived from, so `invalidate` can match it
    * @returns {Promise<*>}
    */
-  load(key, run) {
+  load(key, run, spec) {
     const store = this.website?.dataStore
     if (store?.has(key)) return Promise.resolve(store.get(key).data)
     if (this._inflight.has(key)) return this._inflight.get(key)
     const pending = run()
       .then((data) => {
         store?.set(key, { data })
-        this.remember(key)
+        this.remember(key, spec)
         return data
       })
       .finally(() => {
@@ -421,8 +468,8 @@ export class ApiClient {
   async readEntity({ schema, uuid, via, signal } = {}) {
     if (!uuid) throw new ApiError({ status: 0, title: 'No Entity', detail: 'readEntity needs a uuid', kind: 'invalid' })
     try {
-      const entity = await this.request('GET', `/entities/${encodeURIComponent(uuid)}`, {
-        query: { model: schema, via, ...this._localeQuery() },
+      const entity = await this.request('GET', ROUTES.read(uuid), {
+        query: { [PARAM.model]: schema, [PARAM.via]: via, ...this._localeQuery() },
         signal,
       })
       return { status: 'ready', entity }
@@ -431,6 +478,164 @@ export class ApiClient {
       throw err
     }
   }
+
+  /**
+   * List the entities of a Model the viewer may see.
+   *
+   * ⭐ **Scoped by the session, not by a filter this package adds.** The answer is
+   * what the viewer may see — an anonymous caller gets what is public, and that is
+   * the gate working rather than an empty result to explain away. ⚠️ A lapsed
+   * session is a `401` and not an empty list (backend, 2026-08-29): treating
+   * `records: []` as "perhaps you are signed out" would re-implement a bug they
+   * already fixed, and tell someone their content was gone when it was not.
+   *
+   * ## Paging is absorbed as far as it can honestly be
+   *
+   * `matched` is the count *before* paging, so `hasMore` is derivable without a
+   * second request. `all: true` asks the server for its own all-mode rather than
+   * looping pages from here — a loop this package ran would be slower, racier, and
+   * a reimplementation of something the route already does.
+   *
+   * ⛔ **No cursor, and no auto-following.** A caller that wants every page of a
+   * large Model says `all: true` and gets one request; a caller that wants pages
+   * gets pages. Inventing a third thing in between would hide which one is
+   * happening, and the cost of "it fetched everything" should be visible in the
+   * call.
+   *
+   * @param {object} args
+   * @param {string} args.schema - the Model, e.g. `@/session`
+   * @param {string} [args.scope] - the visibility scope the route accepts
+   * @param {number} [args.limit]
+   * @param {number} [args.offset]
+   * @param {boolean} [args.all] - one request for the whole slice; ignores limit/offset
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<{ records: object[], matched: number, hasMore: boolean }>}
+   */
+  async listEntities({ schema, scope, limit, offset, all = false, signal } = {}) {
+    if (!schema) {
+      throw new ApiError({ status: 0, title: 'No Model', detail: 'listEntities needs a schema', kind: 'invalid' })
+    }
+    const query = { [PARAM.model]: schema, [PARAM.scope]: scope, ...this._localeQuery() }
+    if (all) query[PARAM.paginate] = false
+    else {
+      if (limit != null) query[PARAM.limit] = limit
+      if (offset != null) query[PARAM.offset] = offset
+    }
+
+    const body = await this.request('GET', ROUTES.list(), { query, signal })
+    const records = Array.isArray(body?.[LIST.records]) ? body[LIST.records] : []
+    // `matched` absent is not zero — it is unknown, and a caller reading zero would
+    // conclude "empty" from a body that just did not say. Fall back to what we hold.
+    const matched = typeof body?.[LIST.matched] === 'number' ? body[LIST.matched] : records.length
+    const seen = (offset || 0) + records.length
+    return { records, matched, hasMore: !all && seen < matched }
+  }
+
+  /**
+   * Write items of one entity — create, update, delete, move — as ONE transaction.
+   *
+   * The ops go out stamped with each item's last-seen token and the response is
+   * absorbed, so a caller never handles a precondition itself. That is the single
+   * most reinventable thing on this wire, and the reason it is absorbed rather
+   * than documented.
+   *
+   * ## ⛔ A conflict is REBASED, never retried
+   *
+   * A `409` means someone else changed the item since this viewer last read it.
+   * The ledger takes the current token off the error, so the caller's *next*
+   * attempt is guarded by the truth rather than by what we believed — and then the
+   * error is thrown.
+   *
+   * ⚖️ **Retrying automatically would be the wrong kind of helpful.** The write
+   * would then succeed, and it would succeed by overwriting a change nobody looked
+   * at. Concurrency is the one place where finishing the job for the caller
+   * destroys the thing the guard exists to protect. ⇒ We remove the *bookkeeping*
+   * and leave the *decision*.
+   *
+   * @param {object} args
+   * @param {string} args.schema - the entity's Model
+   * @param {string} args.uuid - the entity whose items these are
+   * @param {object|object[]} args.ops - one op, or a batch run all-or-nothing
+   * @param {boolean} [args.readback] - ask for the written items back
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<*>} the write response, already absorbed
+   */
+  async writeItems({ schema, uuid, ops, readback = false, signal } = {}) {
+    if (!uuid) {
+      throw new ApiError({ status: 0, title: 'No Entity', detail: 'writeItems needs a uuid', kind: 'invalid' })
+    }
+    const list = Array.isArray(ops) ? ops : [ops]
+    if (list.length === 0) {
+      throw new ApiError({ status: 0, title: 'No Ops', detail: 'writeItems needs at least one op', kind: 'invalid' })
+    }
+    const stamped = list.map((op) => this.ledger.stamp(op))
+    const query = { [PARAM.model]: schema }
+    if (readback) query[PARAM.readback] = true
+
+    try {
+      const result = await this.request('POST', ROUTES.items(uuid), {
+        query,
+        body: Array.isArray(ops) ? stamped : stamped[0],
+        signal,
+      })
+      this.ledger.absorb(result)
+      return result
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 409) {
+        // Rebase whichever item the server named. A batch reports one conflict at a
+        // time — the transaction stopped there — so one id is the whole answer.
+        const id = err.extensions?.[FIELD.item] ?? stamped.find((op) => op?.[FIELD.item] != null)?.[FIELD.item]
+        if (id != null) this.ledger.rebase(id, err)
+      }
+      throw err
+    }
+  }
+
+  /**
+   * Create an entity of a Model, optionally with its first items.
+   *
+   * ⚠️ Not idempotent, and deliberately not made so: two calls make two entities.
+   * A caller that must not double-create holds the result, the way it would with
+   * any other create.
+   *
+   * @param {object} args
+   * @param {string} args.schema
+   * @param {object} [args.data] - the initial content, in the Model's own shape
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<*>}
+   */
+  async createEntity({ schema, data, signal } = {}) {
+    if (!schema) {
+      throw new ApiError({ status: 0, title: 'No Model', detail: 'createEntity needs a schema', kind: 'invalid' })
+    }
+    return this.request('POST', ROUTES.create(), {
+      query: { [PARAM.model]: schema },
+      body: data ?? {},
+      signal,
+    })
+  }
+
+  /**
+   * Delete an entity. Its items cascade.
+   *
+   * ⚠️ `revRefPolicy` decides what happens when another entity references this
+   * one. The route's own default refuses — which is the safe direction, and the
+   * one this package keeps by not choosing for the caller.
+   *
+   * @param {object} args
+   * @param {string} args.uuid
+   * @param {'abort'|'orphan_refs'} [args.revRefPolicy]
+   * @param {AbortSignal} [args.signal]
+   */
+  async deleteEntity({ uuid, revRefPolicy, signal } = {}) {
+    if (!uuid) {
+      throw new ApiError({ status: 0, title: 'No Entity', detail: 'deleteEntity needs a uuid', kind: 'invalid' })
+    }
+    return this.request('DELETE', ROUTES.remove(uuid), {
+      query: { [PARAM.revRefPolicy]: revRefPolicy },
+      signal,
+    })
+  }
 }
 
 // Reached only on a `@uniweb/core` older than the `api` slot, where the sealed
@@ -491,6 +696,14 @@ export const requestPasswordReset = (fields) => required().requestPasswordReset(
 export const confirmPasswordReset = (fields) => required().confirmPasswordReset(fields)
 /** @see ApiClient#readEntity */
 export const readEntity = (args) => required().readEntity(args)
+/** @see ApiClient#listEntities */
+export const listEntities = (args) => required().listEntities(args)
+/** @see ApiClient#writeItems */
+export const writeItems = (args) => required().writeItems(args)
+/** @see ApiClient#createEntity */
+export const createEntity = (args) => required().createEntity(args)
+/** @see ApiClient#deleteEntity */
+export const deleteEntity = (args) => required().deleteEntity(args)
 
 export { ApiError, kindOf } from './errors.js'
 export { Ledger } from './ledger.js'

package/src/hooks/useEntity.js

@@ -54,7 +54,7 @@ export function useEntity(ref) {
     if (!key || entry) return undefined
     let live = true
     setError(null)
-    client.load(key, () => client.readEntity(ref)).catch((err) => {
+    client.load(key, () => client.readEntity(ref), { schema: ref.schema, uuid: ref.uuid }).catch((err) => {
       if (live) setError(err)
     })
     return () => {