@uniweb/api 0.1.0 → 0.2.1

package/src/mock/seed.js

@@ -0,0 +1,51 @@
+/**
+ * The default seed — a conference programme, because it is the shape the demo
+ * template uses and a seed nobody edits should still show something.
+ *
+ * ⭐ **A seed is the mock's whole data model**, and it is a plain object on purpose:
+ * a developer edits it in one file, diffs it, and commits it. That is the property
+ * a database would take away.
+ *
+ * ⚠️ `schemas` here lists only what the mock ENFORCES — who may create, and which
+ * sections are insert-only. It is not a data-schema and cannot validate content;
+ * the real schema lives in the foundation, where the site build reads it.
+ */
+export const DEFAULT_SEED = {
+  accounts: [
+    // The organiser belongs to a unit, so `creatable_by: unit_members` lets them
+    // author the programme.
+    { username: 'organiser', password: 'organiser', handle: 'organiser', units: ['conf'], roles: ['member'] },
+    // The attendee belongs to none — the same rule refuses them, server-side, and
+    // that refusal is the demo.
+    { username: 'attendee', password: 'attendee', handle: 'attendee', units: [], roles: ['member'] },
+  ],
+  schemas: {
+    '@/track': { creatable_by: 'unit_members' },
+    '@/session': { creatable_by: 'unit_members' },
+    // 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', append_only: ['checkins'] },
+  },
+  entities: [
+    {
+      uuid: 'track-main',
+      model: '@/track',
+      data: { name: 'Main hall' },
+      items: [
+        { id: 'sess-1', section: 'sessions', data: { title: 'Opening keynote', room: 'Hall A', minutes: 45 } },
+        { id: 'sess-2', section: 'sessions', data: { title: 'Designing for the edge', room: 'Hall A', minutes: 30 } },
+        { id: 'sess-3', section: 'sessions', data: { title: 'Closing panel', room: 'Hall A', minutes: 60 } },
+      ],
+    },
+    {
+      uuid: 'track-workshops',
+      model: '@/track',
+      data: { name: 'Workshops' },
+      items: [
+        { id: 'sess-4', section: 'sessions', data: { title: 'Hands-on: foundations', room: 'Room 2', minutes: 90 } },
+      ],
+    },
+  ],
+}
+
+export default DEFAULT_SEED

package/src/mock/store.js

@@ -0,0 +1,288 @@
+import { FIELD, OP } from '../wire.js'
+
+/**
+ * The mock's state — accounts, one session, entities and their items.
+ *
+ * ⭐ **Seeded fixtures plus in-memory mutation, and deliberately not a database.**
+ * A mock's job is fidelity to what `@uniweb/api` *expects*, not to how a real store
+ * is built. Reach for SQLite and the mock grows a schema, then migrations that
+ * mirror someone else's, and it stops being a fixture and starts being a second
+ * implementation nobody asked for — one that will drift and be believed anyway.
+ *
+ * ⛔ **It is also not a model of `uniwebd`.** Nothing here is evidence about the
+ * real backend. It answers what this client asks, in the shapes this client's own
+ * tests assert, and where those shapes are guesses they are guesses here too —
+ * see `../wire.js` § ASSUMPTIONS.
+ *
+ * What it *does* enforce is the part a demo would otherwise fake: `creatable_by`
+ * and `append_only` are checked server-side, so a foundation that hides a button
+ * still cannot write. That is the difference between showing a permission model
+ * and asserting one.
+ */
+
+let counter = 0
+const nextId = (prefix) => `${prefix}-${(counter += 1)}`
+const now = () => new Date().toISOString()
+
+/** A token that changes on every write — the shape of the value does not matter, only that it moves. */
+const stamp = () => `${Date.now().toString(36)}-${(counter += 1).toString(36)}`
+
+export class MockStore {
+  /**
+   * @param {object} seed
+   * @param {object[]} [seed.accounts] - `{ username, password, handle, roles?, units? }`
+   * @param {object} [seed.schemas] - `{ '@/session': { creatable_by?, append_only? } }`
+   * @param {object[]} [seed.entities] - `{ uuid?, model, data?, items? }`
+   */
+  constructor(seed = {}) {
+    this.accounts = (seed.accounts || []).map((a) => ({
+      uuid: a.uuid || nextId('acct'),
+      username: a.username,
+      password: a.password,
+      handle: a.handle || a.username,
+      roles: a.roles || ['member'],
+      units: a.units || [],
+      ...a,
+    }))
+    // What the mock knows about a Model: only the two things it must ENFORCE.
+    // Everything else about a schema is the site's business, not the server's.
+    this.schemas = seed.schemas || {}
+    this.entities = new Map()
+    for (const e of seed.entities || []) this.seedEntity(e)
+    /** The one session. A mock serves one developer, so one is the honest number. */
+    this.session = null
+    this.resets = new Map()
+  }
+
+  seedEntity({ uuid, model, data = {}, items = [], owner = null }) {
+    const id = uuid || nextId('ent')
+    this.entities.set(id, {
+      uuid: id,
+      model,
+      owner,
+      data,
+      updated_at: now(),
+      items: items.map((item) => this.makeItem(item)),
+    })
+    return this.entities.get(id)
+  }
+
+  makeItem({ section = 'items', data = {}, parent = null, id } = {}) {
+    return {
+      [FIELD.item]: id || nextId('item'),
+      section,
+      [FIELD.parent]: parent,
+      data,
+      created_at: now(),
+      [FIELD.token]: stamp(),
+    }
+  }
+
+  // ── Identity ────────────────────────────────────────────────────────────────
+
+  signIn(username, password) {
+    const account = this.accounts.find((a) => a.username === username)
+    if (!account || account.password !== password) return null
+    this.session = { account, at: now() }
+    return this.viewer()
+  }
+
+  signOut() {
+    this.session = null
+  }
+
+  register(fields) {
+    if (this.accounts.some((a) => a.username === fields.username)) return null
+    const account = {
+      uuid: nextId('acct'),
+      handle: fields.handle || fields.username,
+      roles: ['member'],
+      units: [],
+      ...fields,
+    }
+    this.accounts.push(account)
+    return account
+  }
+
+  /**
+   * The viewer, in the shape `/auth/me` answers.
+   *
+   * ⚠️ `acting_unit_id` is the unit signal, and it is the field the CLIENT already
+   * models (`viewer.actingUnitId`) — so a UI asks the package rather than inventing
+   * its own idea of membership. A mock that omitted it would push every consumer to
+   * invent one, which is how two apps end up disagreeing about who an organiser is.
+   */
+  viewer() {
+    if (!this.session) return null
+    const { uuid, username, handle, roles, units } = this.session.account
+    return {
+      account: { uuid, username, handle },
+      roles,
+      acting_unit_id: units?.length ? units[0] : null,
+    }
+  }
+
+  get account() {
+    return this.session?.account ?? null
+  }
+
+  // ── The rules the mock actually enforces ────────────────────────────────────
+
+  /**
+   * May the viewer create entities of this Model?
+   *
+   * ⭐ The default is OPEN — anyone with an account — and only a schema's
+   * `creatable_by` narrows it. That matches the real store, and it matters that the
+   * mock copies the DIRECTION rather than inventing a safer one: a demo whose mock
+   * denies by default would hide exactly the mistake `creatable_by` exists to
+   * prevent, and someone would ship a Model that anyone can write to having
+   * "tested" it here.
+   */
+  mayCreate(model) {
+    if (!this.account) return false
+    const rule = this.schemas[model]?.creatable_by || 'any_user'
+    if (rule === 'any_user') return true
+    if (rule === 'unit_members') return (this.account.units || []).length > 0
+    return false
+  }
+
+  /** Is this section insert-only? Existing items may not be edited or removed. */
+  isAppendOnly(model, section) {
+    const decl = this.schemas[model]?.append_only
+    if (decl === true) return true
+    return Array.isArray(decl) ? decl.includes(section) : false
+  }
+
+  // ── Reads ───────────────────────────────────────────────────────────────────
+
+  list({ model, limit, offset, all }) {
+    // Scoped by the session the way the real route is: what the viewer may see.
+    // A mock that returned everything would make an entitlement bug invisible.
+    const rows = [...this.entities.values()].filter(
+      (e) => e.model === model && (e.owner === null || e.owner === this.account?.uuid),
+    )
+    const matched = rows.length
+    const page = all ? rows : rows.slice(offset || 0, (offset || 0) + (limit ?? rows.length))
+    return { entities: page.map((e) => this.hydrate(e)), matched }
+  }
+
+  read(uuid) {
+    const entity = this.entities.get(uuid)
+    if (!entity) return null
+    if (entity.owner && entity.owner !== this.account?.uuid) return null
+    return this.hydrate(entity)
+  }
+
+  hydrate(entity) {
+    return {
+      uuid: entity.uuid,
+      model: entity.model,
+      ...entity.data,
+      items: entity.items.map((i) => ({ ...i })),
+    }
+  }
+
+  // ── Writes ──────────────────────────────────────────────────────────────────
+
+  create(model, data) {
+    const entity = this.seedEntity({ model, data, owner: this.account?.uuid ?? null })
+    return this.hydrate(entity)
+  }
+
+  remove(uuid) {
+    return this.entities.delete(uuid)
+  }
+
+  /**
+   * Apply one op. Returns `{ ok, result }` or `{ ok: false, problem }` — the caller
+   * turns a problem into the response, so a batch can stop at the first one and
+   * report which op failed.
+   */
+  applyOp(entity, op) {
+    const kind = op?.kind
+    const itemId = op?.[FIELD.item]
+    const item = itemId != null ? entity.items.find((i) => String(i[FIELD.item]) === String(itemId)) : null
+
+    if (kind !== OP.create) {
+      if (!item) {
+        return { ok: false, problem: { status: 404, title: 'NotFound', kind: 'item', [FIELD.item]: itemId } }
+      }
+      // Append-only guards EDIT and DELETE. Not `move`: `created_at` is the
+      // chronology and a reader orders by it, so repositioning loses no truth.
+      if (kind !== OP.move && this.isAppendOnly(entity.model, item.section)) {
+        return {
+          ok: false,
+          problem: { status: 409, title: 'AppendOnly', detail: `items of '${item.section}' may be added but not changed`, [FIELD.item]: itemId },
+        }
+      }
+      const expected = op?.[FIELD.precondition]
+      if (expected != null && expected !== item[FIELD.token]) {
+        return {
+          ok: false,
+          problem: { status: 409, title: 'Conflict', [FIELD.item]: itemId, [FIELD.conflictToken]: item[FIELD.token] },
+        }
+      }
+    }
+
+    if (kind === OP.create) {
+      // ⛔ No default. A create with no section is a client bug, and defaulting it
+      // would place the item outside the rules its author declared — silently.
+      if (!op[FIELD.section]) {
+        return { ok: false, problem: { status: 400, title: 'Validation', detail: 'create needs a section' } }
+      }
+      const made = this.makeItem({ section: op[FIELD.section], data: op.data, parent: op[FIELD.parent] ?? null })
+      this.place(entity, made, op.position)
+      return { ok: true, result: { [FIELD.item]: made[FIELD.item], [FIELD.token]: made[FIELD.token] } }
+    }
+    if (kind === OP.update) {
+      // Whole-data replace, like the real write: round-trip what you do not edit.
+      item.data = op.data ?? {}
+      item[FIELD.token] = stamp()
+      return { ok: true, result: { [FIELD.item]: item[FIELD.item], [FIELD.token]: item[FIELD.token] } }
+    }
+    if (kind === OP.delete) {
+      entity.items = entity.items.filter((i) => i !== item)
+      // A null token is how a delete reports itself, so a ledger forgets the item.
+      return { ok: true, result: { [FIELD.item]: item[FIELD.item], [FIELD.token]: null } }
+    }
+    if (kind === OP.move) {
+      entity.items = entity.items.filter((i) => i !== item)
+      this.place(entity, item, op.position)
+      item[FIELD.token] = stamp()
+      return { ok: true, result: { [FIELD.item]: item[FIELD.item], [FIELD.token]: item[FIELD.token] } }
+    }
+    return { ok: false, problem: { status: 400, title: 'Validation', detail: `unknown op kind '${kind}'` } }
+  }
+
+  /** Ordering is the server's: `'first' | 'last' | { after }`, never a number from the client. */
+  place(entity, item, position) {
+    if (position === 'first') {
+      entity.items.unshift(item)
+      return
+    }
+    if (position && typeof position === 'object' && position.after != null) {
+      const at = entity.items.findIndex((i) => String(i[FIELD.item]) === String(position.after))
+      if (at >= 0) {
+        entity.items.splice(at + 1, 0, item)
+        return
+      }
+    }
+    entity.items.push(item)
+  }
+
+  /** A batch is all-or-nothing: apply to a copy, and keep it only if every op lands. */
+  applyOps(entity, ops) {
+    const snapshot = entity.items.map((i) => ({ ...i }))
+    const results = []
+    for (const op of ops) {
+      const outcome = this.applyOp(entity, op)
+      if (!outcome.ok) {
+        entity.items = snapshot
+        return { ok: false, problem: outcome.problem }
+      }
+      results.push(outcome.result)
+    }
+    entity.updated_at = now()
+    return { ok: true, results }
+  }
+}

package/src/wire.js

@@ -0,0 +1,243 @@
+/**
+ * The wire — every shape this package asserts about the backend, in one place.
+ *
+ * ## Why this module exists
+ *
+ * Framework is building this client **ahead of backend's per-operation spec**, on
+ * purpose: a client that has actually been built finds things a spec review does
+ * not, and backend asked for exactly this — *"whatever the package asserts about
+ * our responses becomes a consumer we must not break silently. Tell us what you
+ * pin, and we will treat it as a contract."*
+ *
+ * ⛔ **The risk in building ahead is not guessing a shape — that is cheap to fix.
+ * It is guessing a shape, spreading it across a dozen files, and writing it into a
+ * doc as fact.** A wrong assumption that lives in one module is a one-file diff. The
+ * same assumption inlined into six hooks is an archaeology exercise, and by then
+ * something will be citing it as though it were measured.
+ *
+ * ⇒ **So every route, parameter name and response field this package depends on is
+ * declared here, with where it came from.** Three provenances, and the difference
+ * between them is the whole point:
+ *
+ * | | means |
+ * |---|---|
+ * | **RULED** | a person with the authority decided it. Not a measurement — a decision |
+ * | **MEASURED** | observed in a working client of THIS route, or in backend's own source |
+ * | **ASSUMED** | ⛔ **we are building ahead. Nobody has confirmed this.** |
+ *
+ * ⚠️ **`MEASURED` is not `MEASURED HERE`.** A shape read off a *different route* of
+ * the same daemon is `ASSUMED` for ours, however identical it looks — the site
+ * lane and the entity lane are two routes in one binary and may answer
+ * differently. That distinction is the one this file exists to keep, because it is
+ * exactly the one that erodes.
+ *
+ * ## What to do with it
+ *
+ * `ASSUMPTIONS` below is the list to hand backend. When one is confirmed, move its
+ * note to MEASURED and delete its entry — the test on that array makes the change
+ * deliberate and visible rather than a quiet edit.
+ *
+ * @module @uniweb/api/wire
+ */
+
+/**
+ * The lane. ⭐ **RULED** *(Diego, 2026-09-01)*: this package reads and writes
+ * **entities**, and touches nothing under `/api/sites/*`.
+ *
+ * Those routes are not merely unnecessary — they **create sites**, which is the
+ * app's job, not a foundation's, and on a site's own service-provider backend they
+ * have nothing to address anyway: no site of that id lives in that database. *"Our
+ * recursion ends there, right before creating sites."*
+ *
+ * ⛔ Do not add a route here that does not begin `/entities`, or an auth route.
+ */
+export const ENTITIES = '/entities'
+
+/**
+ * Auth. **MEASURED** — shipped in `@uniweb/api@0.1.0` and exercised by the live
+ * suite (`tests/live/`) against a real `uniwebd`.
+ */
+export const AUTH = {
+  me: '/auth/me',
+  login: '/auth/login',
+  challenge: '/auth/login/challenge',
+  logout: '/auth/logout',
+  register: '/auth/register',
+  resetRequest: '/auth/reset/request',
+  resetConfirm: '/auth/reset/confirm',
+}
+
+/**
+ * Entity routes. **MEASURED** — every one of these is called by a working client
+ * of this exact lane, which verified them against the daemon's own controller.
+ *
+ * ⚠️ Measured means *the route exists and answers*. It does **not** mean this
+ * package has confirmed the response bodies — see `ASSUMPTIONS`.
+ */
+export const ROUTES = {
+  /** `GET /entities?model=…` — the door. RULED: this one, not the site door. */
+  list: () => ENTITIES,
+  /** `GET /entities/{uuid}?model=…` — one hydrated entity. */
+  read: (uuid) => `${ENTITIES}/${encodeURIComponent(uuid)}`,
+  /** `POST /entities/batch` — many hydrated entities in one call. */
+  readBatch: () => `${ENTITIES}/batch`,
+  /** `POST /entities?model=…` — create an entity, optionally with its items. */
+  create: () => ENTITIES,
+  /** `POST /entities/{uuid}/items` — the item op. An array body is one transaction. */
+  items: (uuid) => `${ENTITIES}/${encodeURIComponent(uuid)}/items`,
+  /** `DELETE /entities/{uuid}` — hard-delete; items cascade. */
+  remove: (uuid) => `${ENTITIES}/${encodeURIComponent(uuid)}`,
+  /** `POST /entities/delete` — bulk hard-delete, all-or-nothing on the pin guard. */
+  removeBatch: () => `${ENTITIES}/delete`,
+}
+
+/**
+ * Query parameter names. **MEASURED**, with one open question.
+ *
+ * ⚠️ `via` vs `depth`: this package sends `via` on a single-entity read — reading
+ * an entity *through* a container the viewer holds an entitlement on. The working
+ * client of this route sends `depth` / `max_depth` instead and no `via` at all.
+ * Both are presumably valid on the same route, answering different questions, but
+ * **nobody has confirmed they compose** — see `ASSUMPTIONS`.
+ */
+export const PARAM = {
+  model: 'model',
+  scope: 'scope',
+  limit: 'limit',
+  offset: 'offset',
+  locale: 'locale',
+  paginate: 'paginate',
+  via: 'via',
+  depth: 'depth',
+  maxDepth: 'max_depth',
+  readback: 'readback',
+  revRefPolicy: 'rev_ref_policy',
+}
+
+/**
+ * Item ops. The kinds, and which of them carry a precondition.
+ *
+ * **MEASURED** for the semantics: `update` and `delete` carry the target item's
+ * last-seen `updated_at` as `if_unmodified_since`; `create` is tokenless; a
+ * mismatch is `409` with `current_updated_at`; a gone item is `404`; an absent
+ * token is last-writer-wins, guarded same-transaction.
+ *
+ * ⛔ **`move` is ASSUMED.** It is in scope as a product requirement — an operator
+ * arranging authored content by hand, where order is a stored fact and not a sort
+ * key — but it was read off the **site** lane, and this lane's own documentation
+ * names only `update` and `delete` as token-carrying. Whether `move` exists here at
+ * all is unconfirmed.
+ */
+export const OP = {
+  create: 'create',
+  update: 'update',
+  delete: 'delete',
+  move: 'move',
+}
+
+/** Ops that carry `if_unmodified_since`. `create` has no target to guard. */
+export const GUARDED_OPS = new Set([OP.update, OP.delete, OP.move])
+
+/**
+ * Field names on an op and on a write response.
+ *
+ * ⛔ **ASSUMED, all of them.** These were read off `POST /api/sites/{id}/content/items`
+ * — a *different route* of the same binary — because the working client of *our*
+ * route returns its responses unnormalized and so reveals no names at all.
+ *
+ * The shapes are very likely identical: both are `…/items` routes with the same op
+ * vocabulary, and this lane's documentation says its concurrency is "aligned with
+ * the sites lane". **Likely is not measured**, and this comment is the difference.
+ */
+export const FIELD = {
+  /** Names the target item on an op, and the affected item on a response. */
+  item: 'item_id',
+  /** Placement on a `create`. */
+  parent: 'parent_item_id',
+  /**
+   * Which section of the entity an item belongs to.
+   *
+   * ⛔ REQUIRED on a create, and its absence is silent. An entity has several
+   * sections and they are not interchangeable: a rule declared on one — an
+   * `append_only`, a field set — simply does not apply to an item that landed in
+   * another. A create with no section is accepted, stored somewhere, and every
+   * guarantee the author declared is quietly not in force.
+   */
+  section: 'section',
+  /** The precondition an op carries. */
+  precondition: 'if_unmodified_since',
+  /** The item's next token, on a write response. */
+  token: 'item_updated_at',
+  /** The item's current token, on a `409`. */
+  conflictToken: 'current_updated_at',
+}
+
+/**
+ * The list response. **MEASURED on this exact route** — a working client of
+ * `GET /api/entities?model=…` documents the body as `{"entities":[],"matched":0}`
+ * and destructures it that way.
+ *
+ * ⭐ `matched` is the count BEFORE paging, which is what makes it worth carrying:
+ * it is the only thing that can answer "is there more" without a second request.
+ *
+ * ⚠️ **An empty list means empty, and has since 2026-08-29.** Before that a lapsed
+ * session was answered anonymously on content routes — a `200` with an empty list,
+ * byte-identical to a genuinely empty result — so a signed-out viewer was told
+ * their content was gone. Every route now answers `401` instead. This package's
+ * default `onUnauthorized: 'session-lost'` is the correct reading of that, and
+ * anything here that treats an empty list as "maybe you are logged out" would be
+ * re-implementing a bug the backend already fixed.
+ */
+export const LIST = {
+  records: 'entities',
+  /** The count before `limit`/`offset` — the total, not the page. */
+  matched: 'matched',
+}
+
+/**
+ * ⛔ THE LIST TO HAND BACKEND — everything this package asserts that nobody has
+ * confirmed. Each entry says what we do, and what breaks if we are wrong.
+ *
+ * ⭐ This is not documentation of the backend. It is a **statement of what we
+ * pinned**, which is the artifact backend asked for. Confirming one is a deliberate
+ * edit here plus a moved comment above; `tests/wire.test.js` pins the set so the
+ * change cannot be quiet.
+ */
+export const ASSUMPTIONS = [
+  {
+    id: 'write-response-fields',
+    we: `a write response names its item as '${FIELD.item}' and its next token as '${FIELD.token}'`,
+    from: 'the site-editor lane, which is a different route',
+    breaks: 'the ledger records nothing, so every second write on an item goes out unguarded — last-writer-wins instead of a 409',
+  },
+  {
+    id: 'op-field-names',
+    we: `an op names its target '${FIELD.item}', its placement '${FIELD.parent}', and its precondition '${FIELD.precondition}'`,
+    from: 'the site-editor lane, which is a different route',
+    breaks: 'writes are refused, loudly — the cheapest of these to be wrong about',
+  },
+  {
+    id: 'move-exists',
+    we: `'${OP.move}' is an op on this lane, and carries a precondition`,
+    from: 'the site-editor lane; this lane documents only update and delete as token-carrying',
+    breaks: 'an operator cannot reorder authored content, which is half of what makes an app an app rather than a CMS',
+  },
+  {
+    id: 'move-position',
+    we: 'a move is positioned server-side — "first" | "last" | { after } — and the client never computes an order number',
+    from: 'the site-editor lane',
+    breaks: 'reordering writes the wrong sequence, or needs a client-side order the store does not want',
+  },
+  {
+    id: 'viewer-unit-signal',
+    we: "read a viewer's unit membership from `acting_unit_id` on /auth/me, surfaced as `viewer.actingUnitId`",
+    from: "the field this package already normalizes; whether it is THE membership signal, or one of several, is unconfirmed",
+    breaks: 'an app cannot tell an operator from a member, so it either shows authoring controls to everyone or to nobody — and the refusal only arrives at the write',
+  },
+  {
+    id: 'via-and-depth-compose',
+    we: `'${PARAM.via}' and '${PARAM.depth}' are both valid on a single-entity read, answering different questions`,
+    from: 'via is this package’s own; depth is what the working client of this route sends. Neither has been seen beside the other',
+    breaks: 'an entitled read returns the wrong shape, or one parameter silently wins',
+  },
+]