@uniweb/api 0.5.1 → 0.6.1

package/README.md

@@ -96,11 +96,18 @@ full (`limit`, default 50); `matched` counts the records in this answer, not a t
 
 ```jsx
 const { status, entity } = useEntity({ schema: '@acme/lesson', uuid, via: course.uuid })
-// entity.hydrated.items — the content: { id, section_id, data, … } each
+// entity.hydrated.items — the content: { id, section, section_id, data, … } each
 // entity.hydrated.entity.brief — the summary
 // entity.can_edit — whether this viewer may write to it
+
+const sessions = entity.hydrated.items.filter((item) => item.section === 'sessions')
 ```
 
+`item.section` is the section's name, the word a write takes (`parent/child` for a nested
+section). The package resolves it from the Model's definition, so a component never
+handles a section id. `item.id` is what `useEntityWriter` takes to update, move or remove
+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".
 
@@ -179,7 +186,6 @@ export default createMockBackend({
     ],
     schemas: {
       '@acme/track': {
-        creatable_by: 'unit_members',                    // the operator only; 'any_user' is the default
         sections: {
           track: { kind: 'single', brief: true, fields: { name: { type: 'string', required: true } } },
           sessions: { kind: 'multi', fields: { title: { type: 'string', required: true } } },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.5.1",
+  "version": "0.6.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": {

package/src/client.js

@@ -103,6 +103,32 @@ function viewerWorkspace(ws) {
   return Object.freeze({ unitUuid: ws.unit_uuid ?? null, handle: ws.handle ?? null })
 }
 
+/**
+ * Label each item with its section's NAME — `section`, the word a write takes — from
+ * a Model's sections (`ApiClient.sections`): `sessions`, or `parent/child` for a
+ * nested section. An item whose section the definition does not name stays as it is.
+ *
+ * @param {object[]|undefined} items - `hydrated.items`, labelled in place
+ * @param {Array<{ id: number, name: string, parent: number|null }>|null} sections
+ */
+function labelSections(items, sections) {
+  if (!Array.isArray(items) || !Array.isArray(sections) || !sections.length) return
+  const byId = new Map(sections.map((s) => [s.id, s]))
+  const pathOf = (section) => {
+    const names = []
+    const seen = new Set()
+    for (let at = section; at && !seen.has(at.id); at = byId.get(at.parent)) {
+      seen.add(at.id)
+      names.unshift(at.name)
+    }
+    return names.join('/')
+  }
+  for (const item of items) {
+    const section = item && byId.get(item[READ.itemSection])
+    if (section) item[CREATE.sectionName] = pathOf(section)
+  }
+}
+
 export class ApiClient {
   /**
    * @param {object} uniweb - the page's `Uniweb` singleton
@@ -539,6 +565,13 @@ export class ApiClient {
    * and `hydrated.entity.brief` is its summary. `can_edit` is the write gate's
    * own answer for this viewer.
    *
+   * ⭐ **Each item also carries `section`, its section's NAME** — `sessions`, or a
+   * `parent/child` path for a nested one — the word a write takes, so a component
+   * never meets a section id in either direction. It is this package's label, not
+   * the backend's: resolved from the Model's definition, read beside the entity
+   * (once per viewer, and kept). When the definition cannot be read, items carry
+   * no `section` and the read still succeeds.
+   *
    * ⭐ **The read seeds the concurrency ledger** with each item's `updated_at`, so
    * the first edit of an item is guarded by the version the viewer was shown.
    *
@@ -558,11 +591,18 @@ export class ApiClient {
     if (!schema) throw ApiError.invalid('No Model', 'readEntity needs a schema — the backend reads an entity by its Model')
     const mark = this.ledger.mark()
     try {
-      const entity = await this.request('GET', ROUTES.read(uuid), {
-        query: { [PARAM.model]: schema, [PARAM.via]: via, ...this._localeQuery() },
-        signal,
-      })
-      this.ledger.observe(entity?.[READ.hydrated]?.[READ.items], mark)
+      const [entity, sections] = await Promise.all([
+        this.request('GET', ROUTES.read(uuid), {
+          query: { [PARAM.model]: schema, [PARAM.via]: via, ...this._localeQuery() },
+          signal,
+        }),
+        // A label, not a condition of the read: a definition this viewer cannot read
+        // leaves the items unlabelled.
+        this.sections(schema, signal).catch(() => null),
+      ])
+      const items = entity?.[READ.hydrated]?.[READ.items]
+      this.ledger.observe(items, mark)
+      labelSections(items, sections)
       return { status: 'ready', entity }
     } catch (err) {
       if (err instanceof ApiError && err.kind === 'absent') return { status: 'absent', entity: null }
@@ -651,9 +691,11 @@ export class ApiClient {
    * section names; the item route after it takes ids, and ids differ from one
    * backend to the next. So a name is resolved here, from the Model's definition.
    *
-   * ⚠️ The definition is readable for the Models the viewer may create, and by the
-   * site's operator. Anywhere else this cannot resolve a name, and says so — pass
-   * the section's numeric id instead (an item's `section_id` on a read).
+   * ⚠️ The definition is readable by any signed-in viewer — Models are open, so every
+   * Model is one they may create (2026-09-23; until then only the Models a viewer
+   * could create, and the operator). Where it cannot be read this cannot resolve a
+   * name, and says so — pass the section's numeric id instead (an item's
+   * `section_id` on a read).
    *
    * @param {string} schema
    * @param {string|number} section - a name, a `parent/child` path, or an id

package/src/hooks/useEntity.js

@@ -16,8 +16,10 @@ const DISABLED = Object.freeze({ status: 'absent', entity: null, error: null })
  * ```
  *
  * The entity is the backend's answer: `entity.hydrated.items` is its content —
- * `{ id, section_id, data, … }` each — `entity.hydrated.entity.brief` its summary,
- * and `entity.can_edit` whether this viewer may write to it.
+ * `{ id, section, section_id, data, … }` each, `section` being the section's NAME
+ * (the word a write takes; this package's label, see `readEntity`) —
+ * `entity.hydrated.entity.brief` its summary, and `entity.can_edit` whether this
+ * viewer may write to it.
  *
  * Cached in the site's data store under a key scoped to the viewer, so a
  * sign-in or sign-out changes the key and the record is read again for who

package/src/mock/index.js

@@ -39,7 +39,7 @@ import { DEFAULT_SEED } from './seed.js'
  * 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
+ * anyone signed in may create entries of any Model (Models are open); 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.
  *
@@ -286,15 +286,9 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
         }
         const model = store.model(q.get(PARAM.model))
         if (!model) return notFound('model', q.get(PARAM.model))
-        if (!store.mayCreate(model)) {
-          return problem({
-            status: 403,
-            title: 'Forbidden',
-            detail: `use_model on model ${model.uuid} not permitted`,
-            op: 'use_model',
-            target: `model ${model.uuid}`,
-          })
-        }
+        // ⭐ No creation gate: Models are open (2026-09-23) — anyone signed in may create
+        // entries of any Model. Until then `creatable_by: unit_members` answered `403
+        // use_model` here for a member.
         // Any other top-level key is ignored, exactly as the backend ignores it.
         return answer(store.create(model, items.map((i) => ({ ...i, data: i.data ?? {} }))))
       }

package/src/mock/seed.js

@@ -7,24 +7,24 @@
  *
  * - **`accounts`** — `operator: true` marks the account that runs the site's
  *   service. Everyone else is a member. Seeded accounts are verified.
- * - **`schemas`** — per Model: `creatable_by` (`any_user`, the default, or
- *   `unit_members` — the operator only) and `sections`, the Model's sections as
- *   the framework lowers them. With `sections`, writes are shape-checked.
+ * - **`schemas`** — per Model: `sections`, the Model's sections as the framework
+ *   lowers them. With `sections`, writes are shape-checked. Models are open:
+ *   anyone signed in may create entries of any of them.
  * - **`entities`** — `uuid` must be a UUID, as it is on the wire; content is items,
  *   each naming its section. The entity's `brief` is derived from its brief
  *   section's item, as the backend derives it.
  */
 export const DEFAULT_SEED = {
   accounts: [
-    // The organiser runs the site, so the rule on `@/track` lets them author the programme.
+    // The organiser runs the site, and the programme's tracks are theirs.
     { username: 'organiser', password: 'organiser', operator: true },
-    // The attendee is a member — the same rule refuses them, server-side, and that
-    // refusal is the demo. They may record attending, which anyone may.
+    // The attendee is a member. They may make entries of their own — recording
+    // attending is the demo — and may not edit the organiser's programme: the entry
+    // decides, server-side, and that refusal is the other half of the demo.
     { username: 'attendee', password: 'attendee' },
   ],
   schemas: {
     '@/track': {
-      creatable_by: 'unit_members',
       sections: {
         track: { kind: 'single', brief: true, fields: { name: { type: 'string', required: true } } },
         sessions: {
@@ -36,7 +36,6 @@ export const DEFAULT_SEED = {
     // Check-ins are insert-only: an attendee may record attending, and nobody —
     // including them — may edit or remove it afterwards.
     '@/attendance': {
-      creatable_by: 'any_user',
       sections: {
         attendance: { kind: 'single', brief: true, fields: { who: { type: 'string' } } },
         checkins: { kind: 'multi', append_only: true, fields: { session: { type: 'string' }, at: { type: 'string' } } },

package/src/mock/store.js

@@ -94,7 +94,8 @@ export class MockStore {
    * @param {object[]} [seed.accounts] - `{ username, password, email?, handle?, operator? }`.
    *   Seeded accounts are verified. (`units: [...]` non-empty, the older spelling,
    *   also marks the operator.)
-   * @param {object} [seed.schemas] - `{ '@scope/name': { creatable_by?, sections?, append_only?, migration_debt? } }`.
+   * @param {object} [seed.schemas] - `{ '@scope/name': { sections?, append_only?, migration_debt? } }`.
+   *   ⛔ No `creatable_by` — retired 2026-09-23, Models are open; a seed carrying it is refused.
    *   `sections` is the LOWERED sections map (`{ [name]: { kind | multiple, brief, append_only, fields } }`)
    *   as the framework's normalizer produces it; with it, writes are shape-checked
    *   (`./schema-shape.js`). Without it the sections are inferred: a one-item brief
@@ -117,6 +118,13 @@ export class MockStore {
     for (const a of seed.accounts || []) this.addAccount(a, { verified: true })
 
     this.schemas = seed.schemas || {}
+    for (const [name, decl] of Object.entries(this.schemas)) {
+      if (decl && (decl.creatable_by !== undefined || decl.creatableBy !== undefined)) {
+        throw new Error(
+          `[uniweb/api mock] ${name}: creatable_by is retired — Models are open: anyone signed in may create entries of any Model, and who may see or edit an entry is decided by the entry. Remove it.`
+        )
+      }
+    }
     const floors = seed.memberFloor != null && typeof seed.memberFloor === 'object' ? Object.values(seed.memberFloor) : [seed.memberFloor]
     for (const floor of floors) {
       if (floor != null && !['read', 'edit'].includes(floor)) {
@@ -269,7 +277,6 @@ export class MockStore {
       id: (this.ids.model += 1),
       uuid: newUuid(),
       name,
-      creatable_by: decl?.creatable_by || 'any_user',
       decl: decl || {},
       sections: [],
     }
@@ -314,14 +321,14 @@ export class MockStore {
     return null
   }
 
-  mayCreate(model) {
-    if (!this.account) return false
-    return model.creatable_by === 'any_user' || this.account.operator
-  }
-
-  /** The definition is readable for the Models the viewer may create, and by the operator. */
-  maySeeSchema(model) {
-    return !!this.account && (this.account.operator || model.creatable_by === 'any_user')
+  /**
+   * The definition is readable by anyone signed in. ⭐ Models are open (2026-09-23):
+   * anyone signed in may create entries of any Model, and what protects content is the
+   * entry — `mayEdit`, `mayRead` — never who may create. *(Until then a Model declaring
+   * `creatable_by: unit_members` was the operator's alone, and so was its definition.)*
+   */
+  maySeeSchema() {
+    return !!this.account
   }
 
   /** `GET /models/@scope/name`, in the backend's shape. */