@uniweb/api 0.3.7 → 0.4.0

package/src/hooks/useEntityWriter.js

@@ -1,7 +1,7 @@
 import { useCallback, useMemo, useRef, useState } from 'react'
 import { getClient } from '../client.js'
 import { ApiError } from '../errors.js'
-import { FIELD, OP } from '../wire.js'
+import { CREATE, FIELD, OP } from '../wire.js'
 
 const IDLE = 'idle'
 const SAVING = 'saving'
@@ -11,13 +11,17 @@ const ERROR = 'error'
  * Write the items of one entity, in domain terms.
  *
  * ```jsx
- * const programme = useEntityWriter({ schema: '@/track', uuid: track.uuid })
- * await programme.create({ title: 'Keynote' })          // appended
- * await programme.update(itemId, { room: 'Hall A' })
- * await programme.move(itemId, { after: otherItemId })  // the organiser arranges
- * await programme.remove(itemId)
+ * const programme = useEntityWriter({ schema: '@acme/track', uuid: track.uuid })
+ * await programme.create({ title: 'Keynote' }, { section: 'sessions' })   // appended
+ * await programme.update(item.id, { ...item.data, room: 'Hall A' })       // whole data
+ * await programme.move(item.id, { after: other.id })                     // the organiser arranges
+ * await programme.remove(item.id)
  * ```
  *
+ * An item id is the `id` of an item on a read (`entity.hydrated.items`), an integer.
+ * A section is named as the Model names it; the package resolves it to the id the
+ * backend's item route takes.
+ *
  * ## ⭐ Why a hook wraps ops at all — it is a CCA argument, not an ergonomic one
  *
  * A component that composes `{ kind: 'update', item_id, if_unmodified_since }` has
@@ -40,6 +44,10 @@ const ERROR = 'error'
  * overwriting a change nobody looked at. What to do about someone else's edit is
  * the application's question, and it is usually "tell the person".
  *
+ * ⚠️ `conflict` is ONLY that case. A write the Model's rules refuse — an
+ * insert-only section, a second item in a one-item section — is an `error` of kind
+ * `rule`: nobody else is involved, and the same write will fail the same way.
+ *
  * @param {{ schema: string, uuid: string } | null} target
  * @returns {{
  *   create: Function, update: Function, remove: Function, move: Function,
@@ -70,7 +78,7 @@ export function useEntityWriter(target) {
         if (seq.current === mine) setState({ status: IDLE, error: null, conflict: null })
         return result
       } catch (err) {
-        const conflict = err instanceof ApiError && err.status === 409 ? err : null
+        const conflict = err instanceof ApiError && err.kind === 'conflict' ? err : null
         if (seq.current === mine) setState({ status: ERROR, error: err, conflict })
         throw err
       }
@@ -81,53 +89,61 @@ export function useEntityWriter(target) {
   const api = useMemo(
     () => ({
       /**
-       * Append an item to a section. Tokenless by design — there is no existing item
+       * Add an item to a section. Tokenless by design — there is no existing item
        * to guard. `position` and `parent` are the server's ordering vocabulary,
        * passed through rather than turned into an order number here.
        *
-       * ⛔ `section` is REQUIRED and refused when missing, because getting it wrong
-       * fails SILENTLY: an entity has several sections, the item lands in whichever
-       * one the server defaults to, and every rule the author declared on the
-       * intended section — `append_only` above all — is quietly not in force. The
-       * write succeeds, the data looks present, and the guarantee is gone.
+       * ⛔ `section` is REQUIRED, because an entity has several and they are not
+       * interchangeable: a rule declared on one — insert-only above all — does not
+       * reach an item that landed in another. Name it as the Model does; the client
+       * resolves the name to the id the backend's item route takes. A section that
+       * holds one item takes one create, and is `update`d after that.
        *
        * @param {object} data - the item's content
        * @param {object} opts
        * @param {string} opts.section - which section of the entity this belongs to
-       * @param {string|number} [opts.parent] - a parent item, for nested sections
-       * @param {'first'|'last'|{after: string}} [opts.position]
+       * @param {number} [opts.parent] - a parent item's id, for nested content
+       * @param {'first'|'last'|{after: number}} [opts.position] - default: last
        */
       create: (data, { section, parent, position } = {}) => {
         if (!section) {
           return Promise.reject(
-            new ApiError({
-              status: 0,
-              title: 'No Section',
-              detail: 'create needs a section — an item with no section lands outside the rules declared for it',
-              kind: 'invalid',
-            }),
+            ApiError.invalid(
+              'No Section',
+              'create needs a section — an item with no section lands outside the rules declared for it',
+            ),
           )
         }
         return send({
           kind: OP.create,
-          [FIELD.section]: section,
-          data,
+          [CREATE.sectionName]: section,
+          data: data ?? {},
           ...(parent != null ? { [FIELD.parent]: parent } : {}),
           ...(position != null ? { position } : {}),
         })
       },
       /** Replace an item's data. ⚠️ Whole-data replace — round-trip what you do not edit. */
-      update: (itemId, data) => send({ kind: OP.update, [FIELD.item]: itemId, data }),
+      update: (itemId, data) => {
+        if (data == null || typeof data !== 'object') {
+          return Promise.reject(ApiError.invalid('No Data', "update replaces the item's data whole — pass all of it"))
+        }
+        return send({ kind: OP.update, [FIELD.item]: itemId, data })
+      },
       /** Delete one item. */
       remove: (itemId) => send({ kind: OP.delete, [FIELD.item]: itemId }),
       /**
-       * Reposition an item — `'first' | 'last' | { after: <itemId> }`.
+       * Reposition an item — `'first' | 'last' | { after: <itemId> }`, required.
        *
        * ⛔ The client never computes an order number. Ordering is the server's, and
        * two clients arranging the same list from local sequence numbers is how a
        * list ends up in an order neither of them chose.
        */
-      move: (itemId, position) => send({ kind: OP.move, [FIELD.item]: itemId, position }),
+      move: (itemId, position) => {
+        if (position == null) {
+          return Promise.reject(ApiError.invalid('No Position', "move needs a position — 'first', 'last' or { after }"))
+        }
+        return send({ kind: OP.move, [FIELD.item]: itemId, position })
+      },
       /** Send several ops as ONE transaction — all of them land, or none do. */
       batch: (ops) => send(ops),
       reset: () => setState({ status: IDLE, error: null, conflict: null }),

package/src/hooks/useRecords.js

@@ -17,9 +17,11 @@ const DISABLED = Object.freeze({ status: 'absent', records: NONE, matched: 0, ha
  *
  * ## ⭐ `absent` and an empty `ready` are DIFFERENT, and conflating them is the bug
  *
- * `absent` means **there is no live source** — a site with no service-provider
- * backend, which is the ordinary standalone case and not a failure. `ready` with
- * `records: []` means **the source answered, and there is nothing there.**
+ * `absent` means **there is no live source for this viewer** — a site with no
+ * `api` service, which is the ordinary standalone case, or nobody signed in, since
+ * the backend lists nothing to an anonymous caller (it answers `401`, so no request
+ * is sent once the session is known to be anonymous). `ready` with `records: []`
+ * means **the source answered, and there is nothing there.**
  *
  * A component renders its own static content for the first and an empty state for
  * the second, and they are not interchangeable: telling a visitor "no sessions yet"
@@ -27,10 +29,18 @@ const DISABLED = Object.freeze({ status: 'absent', records: NONE, matched: 0, ha
  * that once answered a lapsed session with an empty list — it reports absence of
  * *access* as absence of *content*.
  *
+ * A record is the entity's summary — `record.brief` holds the brief section's
+ * fields, beside `uuid`, `owner_id` and `via` — and carries no items; read one
+ * 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.
+ *
  * 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.
  *
- * @param {{ schema: string, scope?: string, limit?: number, offset?: number, all?: boolean } | null} query
+ * @param {{ schema: string, scope?: 'accessible'|'mine'|'all', limit?: number, offset?: number, all?: boolean } | null} query
  *   pass null to skip
  * @returns {{ status: string, records: object[], matched: number, hasMore: boolean, error: Error|null, refresh: Function }}
  */
@@ -40,13 +50,15 @@ export function useRecords(query) {
   const store = website?.dataStore ?? null
 
   // Re-key on a viewer change: what the viewer may see is part of the answer.
-  useSyncExternalStore(
+  const session = useSyncExternalStore(
     client ? client.subscribe : noSubscribe,
     client ? () => client.session : noSnapshot,
     client ? () => client.session : noSnapshot,
   )
 
-  const active = !!(client && client.enabled && store && query && query.schema)
+  // Signed out, there is no live source: the backend lists nothing to an anonymous
+  // caller, so asking would only buy a `401`.
+  const active = !!(client && client.enabled && store && query && query.schema && session?.status !== 'anonymous')
   const spec = active
     ? {
         endpoint: '/entities',

package/src/http.js

@@ -11,7 +11,7 @@ export const UNSAFE = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])
 /**
  * Is the base another origin than the page's?
  *
- * A relative base (`/_uw`) is the page's own origin by definition. An absolute
+ * A relative base (`/_api`) is the page's own origin by definition. An absolute
  * one is compared against `location.origin`; where there is no location — a
  * server, a test — an absolute base is treated as cross-origin, which only
  * makes the request carry credentials it would otherwise carry anyway.
@@ -31,11 +31,16 @@ export function isCrossOrigin(base) {
 }
 
 /**
- * `${base}/api${path}?…` — the one composition this package makes.
+ * `${base}${path}?…` — the one composition this package makes.
  *
- * The base is the prefix under which the backend's own route space appears:
- * the passthrough path on the site's origin, an origin under the subdomain
- * shape, or empty on a deployment where the page's own server is the backend.
+ * The base IS the backend's API route space, and every route joins it directly:
+ * `/_api` + `/entities`. On a hosted site `/_api` is a path on the site's own
+ * origin that reaches the backend's `/api/…`; wherever the page reaches a backend
+ * directly, the base is that backend's absolute `…/api`.
+ *
+ * ⛔ **Until 0.4 this inserted `/api` after the base**, reading the base as the
+ * backend's root. On a hosted site that sent every request to `/_api/api/…`, a
+ * route that does not exist — measured, and the reason this comment is here.
  * `null` and `undefined` query values are omitted.
  *
  * @param {string} base
@@ -52,7 +57,7 @@ export function composeUrl(base, path, query) {
     params.set(key, String(value))
   }
   const qs = params.toString()
-  return `${root}/api${p}${qs ? `?${qs}` : ''}`
+  return `${root}${p}${qs ? `?${qs}` : ''}`
 }
 
 /**

package/src/ledger.js

@@ -1,53 +1,42 @@
 /**
- * The concurrency ledger — the last-seen `item_updated_at` per item, and the
- * stamping of `if_unmodified_since` onto the ops that need one.
+ * The concurrency ledger — the last-seen `updated_at` per item, and the stamping
+ * of `if_unmodified_since` onto the ops that need one.
  *
  * The backend guards writes at the item grain: `update`, `delete` and `move` each
  * carry the target item's last-seen `updated_at`; `create` carries none. A
  * mismatch is a `409` whose `current_updated_at` extension names the item's
- * current token, and every write response carries `item_updated_at` — the next
- * precondition to chain forward. Three sources, one token.
+ * current token, and every write result carries `item_updated_at` — the next
+ * precondition to chain forward. **Three sources, one token: a read, a write, a
+ * conflict.**
  *
- * ⭐ `move` IS IN SCOPE, and the reasoning that briefly removed it is kept here
- * because it is the mistake this package invites. It was dropped on 2026-09-01 as
- * "an editor concern — an app's order is a property of the query, sort by a
- * field". **That is true of a MEMBER LIST and false of the apps this package
- * exists for.** An LMS instructor authors a course whose lessons are a curriculum
- * SEQUENCE: the order is authored, stored, and repositioned by hand.
+ * ⛔ **Reads are a source, and until 0.4 nothing fed them in.** A hydrated read
+ * carries each item's `updated_at`, which is exactly the token the FIRST write of
+ * that item must carry. Without it the first edit after a read went out
+ * unguarded — last-writer-wins — and silently overwrote whatever another person
+ * had saved in between, which is the one thing this ledger exists to prevent.
  *
- * ⇒ The trap is generalising from the CONSUMING surface. These apps have two, and
- * both are ours: members read and append (progress, submissions), while OPERATORS
- * author the app's own content — full CRUD over developer-defined schemas,
- * hierarchy included. [Diego, 2026-09-01.]
+ * ⚠️ **A read may not roll a token back.** A read that was sent before this client
+ * wrote an item, and answered after, carries the item's OLDER token. Taking it
+ * would make the next write fail against this client's own change. So a read is
+ * marked when it starts (`mark()`), and its tokens are taken only for items this
+ * client has not written since (`observe()`).
  *
- * ⚠️ UNVERIFIED ON OUR LANE: `move` and its server-managed `position` were read
- * off the site-editor's route, which is not ours. Whether
- * `POST /api/entities/{uuid}/items` offers `move`, and in what shape, is a
- * measurement nobody has taken. `stamp()` needs no branch either way — it guards
- * every non-`create` op — so this docstring is the only thing a finding moves.
+ * ⭐ `move` IS IN SCOPE. It was dropped on 2026-09-01 as "an editor concern — an
+ * app's order is a property of the query". **That is true of a MEMBER LIST and
+ * false of the apps this package exists for**: an instructor authors a course
+ * whose lessons are a sequence, ordered and re-ordered by hand. `move` carries a
+ * precondition like any other op on an existing item.
  *
- * That is the single most reinventable thing on the wire, so it lives here
- * once, as a pure structure with no route knowledge. The writer that composes
- * the request is the next slice; it will `stamp()` before sending, `absorb()`
- * what comes back, and `rebase()` on a conflict.
- *
- * ⛔ **Every field name here now comes from `./wire.js`, and that fixed a real
- * defect rather than tidying one.** This module read an op's target as `op.item`
- * and probed responses through a guess list, `['item', 'item_id', 'id']`. The wire
- * field is `item_id`. So a writer composing a correct op would have handed
- * `stamp()` something whose target it could not see — and `stamp()` returns an
- * unguarded op when it cannot find one, **by design, because an item it has never
- * seen is legitimately last-writer-wins.** The two behaviours are identical from
- * here and opposite in effect: one is "no token known", the other is "the
- * precondition was silently dropped from every write."
- *
- * ⇒ That is the argument for one home per name, in miniature. A guess list cannot
- * fail loudly, because guessing is what it is for.
+ * ⛔ **Every field name here comes from `./wire.js`.** This module once read an
+ * op's target as `op.item` while the wire says `item_id`, so a correct op looked
+ * target-less and went out unguarded — by design, because an item never seen is
+ * legitimately last-writer-wins. The two are identical from here and opposite in
+ * effect. One home per name is what makes that impossible.
  */
 
-import { FIELD, OP } from './wire.js'
+import { FIELD, OP, READ } from './wire.js'
 
-/** An op's or a response's item id, by the one name the wire uses. */
+/** An op's or a result's item id, by the one name the wire uses. */
 function itemIdOf(record) {
   const id = record?.[FIELD.item]
   return id == null ? null : String(id)
@@ -56,9 +45,11 @@ function itemIdOf(record) {
 export class Ledger {
   constructor() {
     this._at = new Map()
+    this._wrote = new Map()
+    this._clock = 0
   }
 
-  /** Record an item's token, from a read or a write response. */
+  /** Record an item's token — from a write, a conflict, or a caller that knows. */
   note(itemId, updatedAt) {
     if (itemId == null || updatedAt == null) return
     this._at.set(String(itemId), updatedAt)
@@ -73,12 +64,37 @@ export class Ledger {
     this._at.delete(String(itemId))
   }
 
+  /** A point in this ledger's history — take one when a read STARTS. */
+  mark() {
+    this._clock += 1
+    return this._clock
+  }
+
+  /**
+   * Take the tokens a read carried — each item's `id` and `updated_at` — except for
+   * items this client wrote after the read began.
+   *
+   * @param {object[]} [items] - a hydrated read's items
+   * @param {number} [mark] - `mark()` taken before the read was sent
+   */
+  observe(items, mark = Infinity) {
+    if (!Array.isArray(items)) return
+    for (const item of items) {
+      const id = item?.[READ.itemId]
+      const at = item?.[READ.itemToken]
+      if (id == null || at == null) continue
+      const key = String(id)
+      if ((this._wrote.get(key) ?? 0) > mark) continue
+      this._at.set(key, at)
+    }
+  }
+
   /**
    * Stamp an op with the precondition it needs. `create` is tokenless by
    * design; an op on an item this ledger has never seen goes out unguarded
    * — last-writer-wins — exactly as the wire treats an absent token.
    *
-   * @param {{ kind: string, item?: string|number }} op
+   * @param {{ kind: string, item_id?: number }} op
    * @returns {object} the op, with `if_unmodified_since` when known
    */
   stamp(op) {
@@ -90,26 +106,41 @@ export class Ledger {
   }
 
   /**
-   * Absorb a write response — one result or a batch of them — recording each
-   * item's next token, and forgetting an item whose token came back `null`,
-   * which is how a delete reports itself.
+   * Absorb a write — one result, or a batch's `results` — recording each item's
+   * next token.
+   *
+   * ⭐ **Pass the ops, and each result is read against the op in its position.**
+   * That is the only way to know what a delete removed: its result names no item
+   * (`item_id: null` — the row is gone), so the item is the one the op named.
+   * Without the ops, a result is read on its own — a create's or an update's
+   * result names its item; a delete's cannot be placed.
    *
-   * @param {object} result
+   * @param {object} result - the write's answer
+   * @param {object|object[]} [ops] - the ops that were sent, in order
    */
-  absorb(result) {
+  absorb(result, ops) {
     if (!result || typeof result !== 'object') return
-    if (Array.isArray(result.results)) {
-      for (const r of result.results) this.absorb(r)
-      return
-    }
-    const id = itemIdOf(result)
-    if (id == null || !(FIELD.token in result)) return
-    if (result[FIELD.token] === null) this.forget(id)
-    else this.note(id, result[FIELD.token])
+    const results = Array.isArray(result.results) ? result.results : [result]
+    const sent = ops == null ? [] : Array.isArray(ops) ? ops : [ops]
+    results.forEach((r, i) => {
+      const op = sent[i]
+      if (op?.kind === OP.delete) {
+        if (itemIdOf(op) != null) this.forget(itemIdOf(op))
+        return
+      }
+      const id = itemIdOf(r) ?? itemIdOf(op)
+      if (id == null || !r || !(FIELD.token in r)) return
+      if (r[FIELD.token] === null) {
+        this.forget(id)
+        return
+      }
+      this.note(id, r[FIELD.token])
+      this._wrote.set(id, this.mark())
+    })
   }
 
   /**
-   * On a `409`, take the item's current token from the error so the next
+   * On a stale `409`, take the item's current token from the error so the next
    * attempt is guarded by the truth rather than by what this ledger believed.
    *
    * @param {string|number} itemId
@@ -118,8 +149,9 @@ export class Ledger {
    */
   rebase(itemId, error) {
     const current = error?.extensions?.[FIELD.conflictToken]
-    if (current == null) return false
+    if (itemId == null || current == null) return false
     this.note(itemId, current)
+    this._wrote.set(String(itemId), this.mark())
     return true
   }
 }