@uniweb/api 0.4.0 → 0.5.0

package/README.md

@@ -53,8 +53,9 @@ function Account() {
 
 `viewer` is flat — `viewer.uuid`, `viewer.username`, `viewer.handle`, and `viewer.roles`,
 a list of `{ role, scope_unit_id }`. A member holds no roles (`[]`); the site's operator
-holds `system_admin`. ⚠️ `viewer.actingUnitId` is the same for every member of a site, so
-it cannot tell an operator from a member. To decide whether to show an edit control for
+holds `system_admin`. ⚠️ `viewer.workspace` — the site service's home org,
+`{ handle: 'home', … }` — is the same for every member, so it cannot tell an operator
+from a member. 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
@@ -83,9 +84,10 @@ live source — no `api` service, or nobody signed in — so render your site's
 Showing "nothing yet" for the first case tells a visitor their content is missing
 when it is simply not being asked for.
 
-⚠️ **Whose records.** The default `scope` is everything the viewer may read, and on a
-site's `api` service **members can read each other's entities**. For "my submissions",
-"my progress", pass `scope: 'mine'`.
+**Whose records.** A member 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. The site's operator reads everything. `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
@@ -202,9 +204,11 @@ will in production, and your site's configuration is identical either way.
 refusals, for every route this package uses. It enforces what your schemas declare —
 who may create entries, 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. Members read each other's entities and write their own; the
-operator writes everything. A new sign-up must be verified: the link is in
-`mock.outbox` (the standalone server prints it). State is in memory: restart to reset.
+than in front of a user. Members read and write their own entities and nothing of each
+other's; the operator reads and writes everything (`memberFloor: 'read'` in the seed
+models a service set up to let members read each other's). A new sign-up must be
+verified: the link is in `mock.outbox` (the standalone server prints it). State is in
+memory: restart to reset.
 
 There is also a standalone server, for a frontend that is not a Uniweb site:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.29.4"
+    "@uniweb/core": "^0.29.8"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/client.js

@@ -93,6 +93,16 @@ const LOADING = Object.freeze({ status: 'loading', viewer: null, error: null })
  * from `website.config` on each call, so the editor's `Website.rebuild()`
  * needs no hook here.
  */
+
+/**
+ * `/auth/me`'s `workspace` — `{ unit_uuid, handle }`, both null when none — as the
+ * viewer carries it: `{ unitUuid, handle }`, or `null` for none (`VIEWER`).
+ */
+function viewerWorkspace(ws) {
+  if (!ws || typeof ws !== 'object' || (ws.unit_uuid == null && ws.handle == null)) return null
+  return Object.freeze({ unitUuid: ws.unit_uuid ?? null, handle: ws.handle ?? null })
+}
+
 export class ApiClient {
   /**
    * @param {object} uniweb - the page's `Uniweb` singleton
@@ -307,7 +317,7 @@ export class ApiClient {
     const viewer = Object.freeze({
       ...account,
       roles: Array.isArray(me?.roles) ? me.roles : [],
-      actingUnitId: me?.acting_unit_id ?? null,
+      workspace: viewerWorkspace(me?.workspace),
     })
     if (this._session.viewer && this._session.viewer.uuid !== viewer.uuid) this.forgetViewer()
     return this.setSession({ status: 'authenticated', viewer, error: null })
@@ -567,9 +577,9 @@ export class ApiClient {
    * there is nothing to list — the backend answers `401`, and a lapsed session is
    * a `401` too, never an empty list (so `records: []` means empty).
    *
-   * ⚠️ **`scope` decides whose.** The default, `accessible`, is everything the
-   * viewer may read — on a site's `api` service that is every member's entities
-   * of the Model, not only the viewer's. `mine` is only what the viewer owns.
+   * `scope` decides whose: the default, `accessible`, is everything the viewer may
+   * read — for a member of a site, their own entities and what was shared with them;
+   * for the operator, everything. `mine` is only what the viewer owns.
    *
    * ## Paging, as far as it can honestly be absorbed
    *
@@ -701,9 +711,11 @@ export class ApiClient {
    * error is thrown. Retrying automatically would succeed by overwriting a change
    * nobody looked at. ⇒ We remove the *bookkeeping* and leave the *decision*.
    *
-   * ⚠️ **The stale `409` does not say which item was stale.** For one guarded op
-   * that is the op's item; in a batch of several it is unknowable, and rebasing a
-   * guessed item would put one item's token on another — so a batch is not rebased.
+   * The stale `409` names its item (`item_id`), and that is the item rebased — in a
+   * batch, which stops at its first stale op, the one that was stale. ⚠️ **A backend
+   * from before 2026-09-18 names none.** Then a single guarded op is rebased on its
+   * own item, and a batch is not rebased at all: a guessed item would put one item's
+   * token on another.
    *
    * @param {object} args
    * @param {string} args.schema - the entity's Model

package/src/hooks/useRecords.js

@@ -34,8 +34,9 @@ const DISABLED = Object.freeze({ status: 'absent', records: NONE, matched: 0, ha
  * entity for those. ⚠️ `matched` counts the records in this answer, not a total:
  * `hasMore` is true when the page came back full.
  *
- * ⚠️ The default scope is everything the viewer may read, which on a site's `api`
- * service includes other members' entities. `scope: 'mine'` is only the viewer's.
+ * The default scope is everything the viewer may read — for a member, their own
+ * entities and what was shared with them; for the operator, everything.
+ * `scope: 'mine'` is only the viewer's own.
  *
  * Cached under a key scoped to the viewer, so a sign-in re-reads the list for who
  * is now looking, and a write through `useEntityWriter` drops it.

package/src/mock/index.js

@@ -36,8 +36,9 @@ import { DEFAULT_SEED } from './seed.js'
  *
  * ## What it models, and what it does not
  *
- * One operator (`operator: true` on a seeded account) and members; every
- * signed-in account reads every entity, the owner and the operator write it;
+ * One operator (`operator: true` on a seeded account) and members; a member reads
+ * and writes their own entities and nothing of another's (unless the seed's
+ * `memberFloor` says the service lets them), the operator reads and writes all;
  * `creatable_by: 'unit_members'` Models are created by the operator only; sign-up
  * leaves an account unverified until the link in `mock.outbox` is followed. It
  * does not model entitlements behind `via`, nested sections, or second factors.
@@ -323,7 +324,8 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
         if (!b || !Array.isArray(b.uuids)) return badRequest('invalid batch body: missing field `uuids`')
         const invalid = b.uuids.find((u) => !isUuid(u))
         if (invalid) return badRequest(`invalid uuid: ${invalid}`)
-        const entities = b.uuids.map((u) => store.entities.get(u)).filter(Boolean)
+        // Unreadable ones drop, like missing ones — the batch shows what the caller can see.
+        const entities = b.uuids.map((u) => store.entities.get(u)).filter((e) => e && store.mayRead(e))
         return json(200, { entities: entities.map((e) => store.read(e, { canEdit: false })) })
       }
 
@@ -369,8 +371,9 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
         if (via && !isUuid(via)) return badRequest(`invalid via uuid: ${via}`)
         const found = target(one[1], q.get(PARAM.model))
         if (found.response) return found.response
-        // The mock models no entitlements: a `via` read is the same read, once the
-        // container exists. Not found and not permitted are one answer, as ever.
+        // Not found and not permitted are one answer. The mock models no entitlements:
+        // a `via` read is the same read, once the container exists.
+        if (!store.mayRead(found.entity)) return notFound('entity', one[1])
         if (via && !store.entities.has(via)) return notFound('entity', one[1])
         return json(200, store.read(found.entity, { locales: locales(q), withItems: depth === 'shallow' || depth === 'deep' }))
       }

package/src/mock/store.js

@@ -13,13 +13,16 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  *   is the entity's `brief`, which the backend maintains — derived here on read.
  * - **Ids are integers, entities are addressed by UUID.** A section, an item, an
  *   entity and an account each have an integer id; an entity's path id is its UUID.
- * - **Every signed-in account reads every entity.** On a site's `api` service
- *   every member acts in the site's one unit, and a member of it may read what is
- *   in it — so members read each other's entities. Writing is for the owner and
- *   the operator.
+ * - **A member reads and writes their own entities, and nothing of another's.**
+ *   Every member of a site acts in the site's one unit, and membership of it
+ *   conveys nothing by itself: another member's entity is private to its owner
+ *   unless shared. A service can be set up to let members read (or edit) each
+ *   other's — the seed's `memberFloor` models that choice. *(Until 2026-09-18 the
+ *   backend gave every member read access to every other member's entities.)*
  * - **The operator** — the account that runs the site's service — holds
  *   `system_admin`, creates the Models only the operator may, and may write
- *   anything. A seeded account is the operator with `operator: true`.
+ *   anything. It is a member of the site's unit like everyone else, so what it
+ *   makes is its own. A seeded account is the operator with `operator: true`.
  *
  * ⛔ **Seeded fixtures plus in-memory mutation, and deliberately not a database.**
  * A mock that grows a schema and migrations becomes a second implementation that
@@ -29,9 +32,20 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  * same read), nested sections, second factors, reference fields.
  */
 
-/** The unit every account of a site acts in — `acting_unit_id` on `/auth/me`. */
+/** The unit every account of a site acts in — an entity's `unit_id`. */
 export const SITE_UNIT = 1
 
+/**
+ * The service's home org — `workspace` on `/auth/me`. A site's service is founded with
+ * one, handle `home`, and enrolls every account in it, the owner included, so a request
+ * that names no workspace lands there. Its own value: it is minted in the service's
+ * database, and has nothing to do with the workspace the site was authored in.
+ */
+export const HOME_ORG = Object.freeze({
+  unit_uuid: '01926d5e-0000-7000-8000-0000000000a0',
+  handle: 'home',
+})
+
 /** The gap between neighbouring items' order numbers, as the backend spaces them. */
 const GAP = 1_000_000
 
@@ -85,6 +99,8 @@ export class MockStore {
    *   seed's items and `append_only` use.
    * @param {object[]} [seed.entities] - `{ uuid?, model, owner?, items?: [{ section, data, parent? }] }`.
    *   `uuid` must be a UUID. (`data`, the older spelling, becomes the brief section's item.)
+   * @param {'read'|'edit'} [seed.memberFloor] - what membership lets one member do to
+   *   ANOTHER member's entities. Absent — the default — nothing: each member's are private.
    * @param {object} [options]
    * @param {string} [options.signedInAs] - start with this account already signed in.
    */
@@ -95,6 +111,11 @@ export class MockStore {
     for (const a of seed.accounts || []) this.addAccount(a, { verified: true })
 
     this.schemas = seed.schemas || {}
+    if (seed.memberFloor != null && !['read', 'edit'].includes(seed.memberFloor)) {
+      throw new Error(`[uniweb/api mock] memberFloor is 'read' or 'edit', or absent — got ${JSON.stringify(seed.memberFloor)}`)
+    }
+    /** What membership lets one member do to another's entities: `null` (nothing), `read` or `edit`. */
+    this.memberFloor = seed.memberFloor ?? null
     this.models = new Map()
     const itemSections = new Map()
     for (const e of seed.entities || []) {
@@ -159,7 +180,9 @@ export class MockStore {
     return {
       account: this.identity(account),
       roles: account.operator ? [{ role: 'system_admin', scope_unit_id: null }] : [],
-      acting_unit_id: SITE_UNIT,
+      // A request that names no workspace — as this package's never do — lands in the
+      // home org, which every account belongs to. Both null would mean a non-member.
+      workspace: { ...HOME_ORG },
     }
   }
 
@@ -406,16 +429,29 @@ export class MockStore {
     return siblings[siblings.length - 1].order_number + GAP
   }
 
+  /** The operator, the owner — or any member, when the service lets members read each other's. */
+  mayRead(entity) {
+    const me = this.account
+    return !!me && (me.operator || entity.owner_id === me.id || this.memberFloor != null)
+  }
+
   mayEdit(entity) {
     const me = this.account
-    return !!me && (me.operator || entity.owner_id === me.id)
+    return !!me && (me.operator || entity.owner_id === me.id || this.memberFloor === 'edit')
   }
 
-  /** Which branch lets the viewer read a row, as the backend names it. */
+  /**
+   * Which branch lets the viewer read a row, as the backend names it — the first to
+   * answer in its order: `owner`, `grant`, `rbac`, `unit_member`. The operator's own rows
+   * are `owner` like anyone's, and the rest it reads as `system_admin`. *(Until
+   * 2026-09-18 the operator was not a member of the site's unit, and ownership speaks
+   * only for a member — so its own rows answered `rbac` too.)*
+   */
   via(entity) {
     const me = this.account
+    if (entity.owner_id === me?.id) return 'owner'
     if (me?.operator) return 'rbac'
-    return entity.owner_id === me?.id ? 'owner' : 'unit_member'
+    return 'unit_member'
   }
 
   /** The entity's summary: its brief section's item, projected like any read. */
@@ -506,7 +542,7 @@ export class MockStore {
   list(model, { scope, limit, offset, paginate, locales }) {
     const me = this.account
     const rows = [...this.entities.values()]
-      .filter((e) => e.model === model.name && (scope !== 'mine' || e.owner_id === me?.id))
+      .filter((e) => e.model === model.name && this.mayRead(e) && (scope !== 'mine' || e.owner_id === me?.id))
       .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : b.id - a.id))
     const page = paginate ? rows.slice(offset, offset + limit) : rows
     // `matched` counts the rows in THIS answer — the page, when paging.
@@ -620,6 +656,7 @@ export class MockStore {
     const expected = op[FIELD.precondition]
     if (expected != null && expected !== item.updated_at) {
       return refuse(409, 'Conflict', 'item changed since your last read — refetch and retry', {
+        [FIELD.item]: item.id,
         [FIELD.conflictToken]: item.updated_at,
       })
     }

package/src/wire.js

@@ -35,9 +35,10 @@
  * | `matched` was read as the total before paging | it counts the rows in THIS answer — the page when paging. A full page is the only "maybe more" |
  * | a read's items did not seed the concurrency ledger | they carry `updated_at`, the token the first write of an item is guarded by |
  * | every `409` was reported as an edit conflict | only the one carrying `current_updated_at` is; the rest are rules (insert-only, one-item section, a reference) |
- * | a `409` was rebased onto "the first op with an item id" | the stale `409` names no item — a batch cannot be rebased by guesswork |
+ * | a `409` was rebased onto "the first op with an item id" | only the item the stale `409` names (`item_id`, since 2026-09-18); an older backend names none, and a batch is then not rebased — never by guesswork |
  * | a sign-up answered with the account | it answers `202 { status: 'verification_required', email }`; the account cannot sign in until verified (`403 Email Not Verified`) |
  * | `acting_unit_id` was a membership signal | every signed-in member of a site acts in the same unit — it cannot tell an operator from a member; `roles` can |
+ * | the viewer carried `actingUnitId` | it carries `workspace` — where the request landed: on a site's service, its home org (2026-09-23; `acting_unit_id` leaves the wire) |
  *
  * @module @uniweb/api/wire
  */
@@ -113,7 +114,7 @@ export const AUTH = {
  * | reset request | `{ email }` | `202 { status: 'reset_requested' }` whether or not the address is known |
  * | reset confirm | `{ token, new_password, code? }` | `200 { reset: true }`; a bad token is `400 Validation`; `code` is required when a second factor is enrolled |
  * | logout | none | `204`; with no session to end, `401` |
- * | me | none | `200 { account: { uuid, username, handle }, roles, acting_unit_id }` · `401` |
+ * | me | none | `200 { account: { uuid, username, handle }, roles, workspace: { unit_uuid, handle } }` · `401` |
  */
 export const AUTH_BODY = {
   login: ['username', 'password'],
@@ -136,16 +137,24 @@ export const TOTP = {
  * `roles` is a list of `{ role, scope_unit_id }` — `role` one of `system_admin`,
  * `unit_admin`, `content_editor`, `user`. An ordinary member holds none: `[]`.
  *
- * ⛔ **`acting_unit_id` is NOT a membership or operator signal.** Every signed-in
- * member of a site acts in the same unit, so it reads the same for the operator
- * and for someone who signed up a minute ago. The operator of a site's `api`
- * service holds `system_admin`. Better than either: ask about the thing — a
- * single-entity read carries `can_edit`, the write gate's own answer.
+ * `workspace` is `{ unit_uuid, handle }` — **the workspace the request works in**. This
+ * package's requests name none, and on a site's `api` service such a request lands in
+ * the service's **home org**, `handle: 'home'`, in which every account is enrolled.
+ * Both `null` there means an account that is not a member — a service account, a
+ * revoked membership. (On a backend with no home org, naming none is personal: both
+ * `null`.) The viewer carries it as `{ unitUuid, handle }`, or `null` when both are
+ * null. *(It replaced `acting_unit_id` on 2026-09-23. MEASURED by backend at the
+ * function the route serializes, 2026-09-23.)*
+ *
+ * ⛔ **Neither is an operator signal.** Every member of a site's service works in the
+ * same home org, so it reads the same for the operator and for someone who signed up a
+ * minute ago. The operator holds `system_admin`. Better than either: ask about the
+ * thing — a single-entity read carries `can_edit`, the write gate's own answer.
  */
 export const VIEWER = {
   account: 'account',
   roles: 'roles',
-  actingUnit: 'acting_unit_id',
+  workspace: 'workspace',
 }
 
 /**
@@ -212,10 +221,14 @@ export const PARAM = {
 }
 
 /**
- * The list's `scope`. **MEASURED.** Default `accessible` — everything the viewer
- * may read. ⚠️ On a site's `api` service that is **every member's** entities of
- * the Model, not only the viewer's own: members of a site read each other's
- * content. `mine` is only what the viewer owns.
+ * The list's `scope`. Default `accessible` — everything the viewer may read; `mine`
+ * — only what the viewer owns.
+ *
+ * What a member of a site may read: their own entities, and what was shared with
+ * them. Other members' entities are private to their owners unless the site's
+ * service was set up to let members read each other's. The operator reads
+ * everything. *(A site's service let every member read every other member's
+ * entities until 2026-09-18 — measured, and changed on the backend.)*
  */
 export const SCOPE = {
   mine: 'mine',
@@ -269,7 +282,11 @@ export const GUARDED_OPS = new Set([OP.update, OP.delete, OP.move])
  * known only from the op that named it.
  */
 export const FIELD = {
-  /** Names the target item on an op (an integer), and the item on a write result. */
+  /**
+   * Names the target item on an op (an integer), the item on a write result, and
+   * the stale item on a `409` — the last since 2026-09-18; an older backend's `409`
+   * carries only `conflictToken`.
+   */
   item: 'item_id',
   /** The new item's uuid, on a create's result. */
   itemUuid: 'item_uuid',
@@ -325,8 +342,10 @@ export const CREATE = {
  * paging; a page that came back full is the only sign there may be more.
  *
  * `via` names why the viewer can read the row — `owner`, `grant`, `rbac`,
- * `unit_member`, `entitlement`; treat an unknown value as "no opinion". ⚠️ An
- * empty list means empty: a lapsed session is a `401`, never `200 []`.
+ * `unit_member`, `entitlement`; treat an unknown value as "no opinion". The
+ * operator's own rows are `owner` and the rest `rbac` — since 2026-09-18; an older
+ * backend answers `rbac` on the operator's own rows too. ⚠️ An empty list means
+ * empty: a lapsed session is a `401`, never `200 []`.
  */
 export const LIST = {
   records: 'entities',
@@ -343,7 +362,10 @@ export const LIST = {
  * section by id only; the Model's definition maps ids to names.
  *
  * `absent` is one word for not-found and not-permitted, by design: both are
- * `404 { kind: 'entity' }`.
+ * `404 { kind: 'entity' }`. So is an entity of ANOTHER Model: `?model=` says what
+ * the caller takes the entity to be, and a read or a write naming the wrong one is
+ * the same `404` — since 2026-09-18; before that the backend answered, stamped with
+ * the Model named.
  */
 export const READ = {
   hydrated: 'hydrated',
@@ -381,7 +403,7 @@ export const SCHEMA = {
  *
  * | answer | means |
  * |---|---|
- * | `409 Conflict` + `current_updated_at` | the item changed since this viewer's token — the ONLY stale-token answer |
+ * | `409 Conflict` + `item_id`, `current_updated_at` | that item changed since this viewer's token — the ONLY stale-token answer. `item_id` since 2026-09-18; an older backend sends the token alone |
  * | `409 Append-Only Section` + `section` | an insert-only section: its items can be added and moved, not edited or deleted |
  * | `409 Schema Rule Violation` | a rule of the Model: a second item in a one-item section, a section of another Model, a reference that still points here |
  * | `403 Forbidden` + `op`, `target` | may read it, may not do this to it — `edit`, `delete`, `use_model` (create) |