@uniweb/api 0.9.0 → 1.0.1

package/README.md

@@ -81,15 +81,15 @@ import { useMailedLink } from '@uniweb/api'
 
 // Wherever the site's root renders it — a header or a layout is on every page.
 function FromYourEmail() {
-  const { step, status, result, error, confirm } = useMailedLink()
-  if (step === 'verify' && status === 'done') return <p>Your address is confirmed. Sign in.</p>
+  const { step, status, error, confirm } = useMailedLink()
   if (step === 'reset' && status !== 'done') {
     return <NewPassword onSave={(password) => confirm({ new_password: password })} error={error} />
   }
+  if (step === 'verify' && status === 'done') return <p>Your address is confirmed. Sign in.</p>
+  if (step === 'reset' && status === 'done') return <p>Your password is changed. Sign in.</p>
   if (step === 'offer' && status === 'idle') return <p>Sign in, or create an account, to take up your invitation.</p>
-  if (step === 'offer' && status === 'done' && result.invitations + result.grants > 0) return <p>Your invitation is in.</p>
-  if (status === 'error' || status === 'done') return <p>This link can no longer be used.</p>
-  return null
+  if (error?.kind === 'invalid' || error?.kind === 'absent') return <p>This link can no longer be used.</p>
+  return null   // a claimed offer: what it holds is listed by useInvitations, below
 }
 ```
 
@@ -99,14 +99,53 @@ function FromYourEmail() {
   `min_length`), and the same link works again. `offer` waits until someone is signed
   in — whatever their account's own address — and then claims by itself.
 - An offer answers counts, `{ invitations, grants }` — invitations now waiting for this
-  account to accept, and entities now shared with it — never names. Both `0` means it
+  account's answer, and entities now shared with it — never names. Both `0` means it
   bound nothing. ⛔ A token unknown, revoked or already used is ONE answer,
-  `error.kind === 'absent'`: say one sentence, naming no cause.
+  `error.kind === 'absent'`: say one sentence, naming no cause. It is not "no
+  invitation": a member who confirmed the address the offer was sent to holds what it
+  bound already, and its link then answers `absent`.
 - Once the backend has judged the token, it leaves the address bar, so a reload asks
   nothing again; a link the backend could not be reached about (`kind: 'unavailable'`)
   stays, and works on a reload. However many components use the hook, the link is
   finished once. `dismiss()` forgets it unfinished.
 
+**Invitations** — to join an organization on the site's backend. One sent to a member's
+account waits at once (its email is a plain link to your site: they sign in); one sent to
+an address with no account here waits once its `?offer=` link is claimed, or once someone
+signs up with that address and confirms it. `useInvitations()` lists the ones waiting,
+and answers them:
+
+```jsx
+import { useInvitations } from '@uniweb/api'
+
+function Invitations() {
+  const { status, invitations, accept, decline, answering } = useInvitations()
+  if (status !== 'ready') return null
+  return invitations.map((invitation) => (
+    <p key={invitation.id}>
+      {invitation.unit_name ?? 'An organization'} invited you.
+      <button disabled={answering === invitation.id} onClick={() => accept(invitation.id)}>Join</button>
+      <button disabled={answering === invitation.id} onClick={() => decline(invitation.id)}>Decline</button>
+    </p>
+  ))
+}
+```
+
+- An invitation is `{ id, unit_uuid, unit_handle, unit_name, invited_by_account_id,
+  created_at }`, as the backend lists it; `unit_handle` and `unit_name` may be `null`.
+- `absent` — no backend, or nobody signed in. `ready` with `invitations: []` — none
+  waiting.
+- `accept(id)` and `decline(id)` answer one and reject as the backend does; `answering`
+  is the id being answered, `answerError` the last refusal. After either the list reads
+  again. After an accept, so does everything else the viewer has read, and the session
+  is asked again.
+- An invitation that no longer waits — answered in another tab, or withdrawn by its
+  organization — is refused with `kind: 'rule'`, and the list reads again without it.
+  Its `detail` says which, for people: branch on `kind`, never on the words. `absent`
+  means the id is not this member's to answer.
+- ⭐ Draw it wherever a signed-in member lands, not only after an `?offer=` link: an
+  invitation sent to an account comes with no link to follow.
+
 **The Admin link** — some of the site's members administer its backend, the operator
 among them. For them, `adminHref` is the address that takes them to the backend's
 administration, already signed in; for everyone else it is `null`, so draw the link
@@ -275,7 +314,10 @@ each member's own records stay private). The mail the backend would send — a s
 confirmation, a password reset — is printed where the mock runs, in the terminal of
 `uniweb dev`, its link on your site's root as the backend's is, so following it is
 trying your page; the messages are in `mock.outbox` too. To try an invitation, seed one:
-`offers: [{ email: 'guest@example.test', invitations: 1 }]` is mailed when the mock starts.
+`offers: [{ email: 'guest@example.test', invitations: 1 }]` is mailed when the mock starts,
+and claiming it — or signing up with that address and confirming it — leaves the
+invitation waiting. An offer to an address a seeded account holds waits for that account
+from the start.
 The operator's Admin link answers too, landing on a page of the mock's own — the backend's
 administration is not part of it. State is in memory: restart to reset.
 
@@ -290,8 +332,9 @@ npx uniweb-api-mock --port 8787 --site http://localhost:3000
 
 `@uniweb/api/client` carries the same operations as plain functions and imports no
 React: `probeSession`, `signIn`, `listEntities`, `readEntity`, `writeItems`,
-`createEntity`, `deleteEntity`, `adminHref`, and for the links the backend mails,
-`mailedLink`, `verifyEmail`, `claimOffer` and `forgetMailedLink`.
+`createEntity`, `deleteEntity`, `adminHref`, for the links the backend mails,
+`mailedLink`, `verifyEmail`, `claimOffer` and `forgetMailedLink`, and for invitations,
+`listInvitations`, `acceptInvitation` and `declineInvitation`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.9.0",
+  "version": "1.0.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": {
@@ -34,7 +34,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.38.1"
+    "@uniweb/core": "~1.0.1"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/client.js

@@ -18,6 +18,7 @@ import { composeUrl, isCrossOrigin, readBody, UNSAFE } from './http.js'
 import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA, PAGE, TOTP, VIEWER } from './wire.js'
 import { Ledger } from './ledger.js'
 import { verifyEmailWith, claimOfferWith } from './mailed-links.js'
+import { listInvitationsWith, acceptInvitationWith, declineInvitationWith } from './invitations.js'
 
 /**
  * The site service this package reads its base from — the only name it owns.
@@ -476,6 +477,39 @@ export class ApiClient {
     return claimOfferWith(this, token)
   }
 
+  /**
+   * The invitations waiting for the signed-in account's answer — to join an
+   * organization — each as the backend lists it: `{ id, unit_uuid, unit_handle,
+   * unit_name, invited_by_account_id, created_at }`. Nobody signed in throws `auth`.
+   *
+   * @param {{ signal?: AbortSignal }} [options]
+   * @returns {Promise<object[]>}
+   */
+  listInvitations(options) {
+    return listInvitationsWith(this, options)
+  }
+
+  /**
+   * Accept an invitation by its `id`. What the viewer has read is read again, and the
+   * session is asked again.
+   *
+   * @param {number} id
+   * @returns {Promise<object>}
+   */
+  acceptInvitation(id) {
+    return acceptInvitationWith(this, id)
+  }
+
+  /**
+   * Decline an invitation by its `id`.
+   *
+   * @param {number} id
+   * @returns {Promise<object>}
+   */
+  declineInvitation(id) {
+    return declineInvitationWith(this, id)
+  }
+
   // ── The cache ─────────────────────────────────────────────────────────────
 
   /**
@@ -997,6 +1031,12 @@ export const confirmPasswordReset = (fields) => required().confirmPasswordReset(
 export const verifyEmail = (token) => verifyEmailWith(required(), token)
 /** @see ApiClient#claimOffer — on any instance, an older copy's too */
 export const claimOffer = (token) => claimOfferWith(required(), token)
+/** @see ApiClient#listInvitations — on any instance, an older copy's too */
+export const listInvitations = (options) => listInvitationsWith(required(), options)
+/** @see ApiClient#acceptInvitation — on any instance, an older copy's too */
+export const acceptInvitation = (id) => acceptInvitationWith(required(), id)
+/** @see ApiClient#declineInvitation — on any instance, an older copy's too */
+export const declineInvitation = (id) => declineInvitationWith(required(), id)
 /** @see ApiClient#readEntity */
 export const readEntity = (args) => required().readEntity(args)
 /** @see ApiClient#listEntities */

package/src/errors.js

@@ -24,8 +24,9 @@
  *                 ONLY this. Retrying blind would overwrite their change
  *   rule          the write breaks a rule the Model declares — an insert-only
  *                 section, a section that holds one item, a reference that still
- *                 points here. `detail` says which; the same write fails the same
- *                 way again
+ *                 points here — or the backend's own: an invitation is answered
+ *                 once. `detail` says which; the same write fails the same way
+ *                 again
  *   csrf          the mutation lacked the header this package always sends —
  *                 a bug, not a state to handle
  *   step-up       the credential must be re-proven for this mutation
@@ -49,7 +50,8 @@ const TITLE_KINDS = {
  *
  * ⛔ **A `409` is a `conflict` only when it carries `current_updated_at`.** The
  * backend answers `409` for several unrelated refusals — an insert-only section,
- * a second item in a one-item section, a reference that pins an entity — and
+ * a second item in a one-item section, a reference that pins an entity, an
+ * invitation that no longer waits — and
  * reporting those as "someone else changed this first" tells a person to reload
  * and try again when nothing they do will make the write succeed. The token is
  * what marks the stale case; nothing else carries it (measured 2026-09-18).

package/src/hooks/useInvitations.js

@@ -0,0 +1,144 @@
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import { getClient } from '../client.js'
+import { ApiError } from '../errors.js'
+import { INVITATIONS_SPEC, listInvitationsWith, acceptInvitationWith, declineInvitationWith } from '../invitations.js'
+
+const noSubscribe = () => () => {}
+const noSnapshot = () => null
+const NONE = Object.freeze([])
+const QUIET = Object.freeze({ answering: null, answerError: null })
+
+/**
+ * The invitations waiting for the viewer's answer — to join an organization of the
+ * site's backend — and the answers.
+ *
+ * ```jsx
+ * const { status, invitations, accept, decline, answering } = useInvitations()
+ * if (status !== 'ready') return null
+ * return invitations.map((invitation) => (
+ *   <p key={invitation.id}>
+ *     {invitation.unit_name ?? 'An organization'} invited you.
+ *     <button disabled={answering === invitation.id} onClick={() => accept(invitation.id)}>Join</button>
+ *     <button disabled={answering === invitation.id} onClick={() => decline(invitation.id)}>Decline</button>
+ *   </p>
+ * ))
+ * ```
+ *
+ * - `absent` — no backend, or nobody signed in: there is nobody to invite. `ready` with
+ *   `invitations: []` — none waiting.
+ * - Each invitation is as the backend lists it: `{ id, unit_uuid, unit_handle,
+ *   unit_name, invited_by_account_id, created_at }` — `unit_handle` and `unit_name`
+ *   may be `null`.
+ * - `accept(id)` and `decline(id)` answer one, and reject as the backend does;
+ *   `answering` is the id being answered, and `answerError` the last refusal. After
+ *   either the list reads again; after an accept, so does everything else the viewer
+ *   has read, and the session is asked again.
+ * - An invitation that no longer waits — answered in another tab, or withdrawn by its
+ *   organization — is refused with `kind: 'rule'`, its `detail` saying which, for
+ *   people, and the list reads again without it. `absent` — the id is not this
+ *   account's to answer.
+ *
+ * ⭐ **Draw it wherever a signed-in member lands, not only after an `?offer=` link.**
+ * An invitation sent to an account waits with no link to follow, and a member who
+ * confirmed the address an offer was sent to holds its invitation already — its link
+ * then answers `absent` (`useMailedLink`).
+ *
+ * Cached under a key scoped to the viewer, so every component that uses this shares
+ * one request, a sign-in reads the list for who is now looking, and a claim
+ * (`claimOffer`) that leaves invitations waiting reads it again.
+ *
+ * @returns {{
+ *   status: 'absent' | 'loading' | 'ready' | 'error',
+ *   invitations: object[],
+ *   error: Error | null,
+ *   accept: (id: number) => Promise<object>,
+ *   decline: (id: number) => Promise<object>,
+ *   answering: number | null,
+ *   answerError: Error | null,
+ *   refresh: () => void,
+ * }}
+ */
+export function useInvitations() {
+  const client = getClient()
+  const store = client?.website?.dataStore ?? null
+
+  const session = useSyncExternalStore(
+    client ? client.subscribe : noSubscribe,
+    client ? () => client.session : noSnapshot,
+    client ? () => client.session : noSnapshot,
+  )
+
+  // Nothing waits for nobody, so the list waits for the session to be known.
+  useEffect(() => {
+    if (client?.enabled) client.ensureSession()
+  }, [client])
+
+  const active = !!(client && client.enabled && store && session?.status === 'authenticated')
+  const key = active ? client.cacheKey(INVITATIONS_SPEC) : null
+
+  const subscribe = useCallback((fn) => (key ? store.subscribe(key, fn) : noSubscribe()), [store, key])
+  const entry = useSyncExternalStore(
+    subscribe,
+    () => (key ? store.get(key) : null),
+    () => (key ? store.get(key) : null),
+  )
+
+  const [error, setError] = useState(null)
+  const [attempt, setAttempt] = useState(0)
+  const [answer, setAnswer] = useState(QUIET)
+
+  const live = useRef(true)
+  useEffect(() => {
+    live.current = true
+    return () => {
+      live.current = false
+    }
+  }, [])
+  // An answer in flight must not be reported by a later render of a stale closure.
+  const seq = useRef(0)
+
+  useEffect(() => {
+    if (!key || entry) return undefined
+    let current = true
+    setError(null)
+    client.load(key, () => listInvitationsWith(client), INVITATIONS_SPEC).catch((err) => {
+      if (current) setError(err)
+    })
+    return () => {
+      current = false
+    }
+  }, [client, key, entry, attempt])
+
+  const respond = useCallback(
+    async (run, id) => {
+      if (!client || !client.enabled) throw ApiError.disabled()
+      const mine = (seq.current += 1)
+      setAnswer({ answering: id, answerError: null })
+      try {
+        const result = await run(client, id)
+        if (live.current && seq.current === mine) setAnswer(QUIET)
+        return result
+      } catch (err) {
+        if (live.current && seq.current === mine) setAnswer({ answering: null, answerError: err })
+        throw err
+      }
+    },
+    [client],
+  )
+
+  const accept = useCallback((id) => respond(acceptInvitationWith, id), [respond])
+  const decline = useCallback((id) => respond(declineInvitationWith, id), [respond])
+
+  const refresh = useCallback(() => {
+    if (key && store) store.delete(key)
+    setAttempt((n) => n + 1)
+  }, [store, key])
+
+  const actions = { accept, decline, ...answer, refresh }
+  if (!active) return { status: 'absent', invitations: NONE, error: null, ...actions }
+  if (entry) return { status: 'ready', invitations: entry.data, error: null, ...actions }
+  if (error) return { status: 'error', invitations: NONE, error, ...actions }
+  return { status: 'loading', invitations: NONE, error: null, ...actions }
+}
+
+export default useInvitations

package/src/hooks/useMailedLink.js

@@ -22,7 +22,7 @@ const noSnapshot = () => null
  * // link.status: 'idle' | 'working' | 'done' | 'error'
  * if (link.step === 'verify' && link.status === 'done') return <p>Your address is confirmed. Sign in.</p>
  * if (link.step === 'reset' && link.status !== 'done') return <NewPassword onSubmit={(p) => link.confirm({ new_password: p })} />
- * if (link.step === 'offer' && link.status === 'done') return <p>{link.result.invitations} invitation(s) waiting for you.</p>
+ * if (link.step === 'offer' && link.status === 'idle') return <p>Sign in, or create an account, to take up your invitation.</p>
  * ```
  *
  * - **`verify`** finishes by itself: `working`, then `done` (`result: { verified: true }`),
@@ -34,10 +34,12 @@ const noSnapshot = () => null
  *   'password_too_short'` and `min_length`, and the same link works again.
  * - **`offer`** waits for a sign-in — `idle` until someone is signed in, so offer the
  *   sign-in and sign-up — then claims by itself: `done` with `result: { invitations,
- *   grants }`, COUNTS — invitations waiting for this account to accept, entities now
- *   shared with it — or `error`, `kind: 'absent'` for a token unknown, revoked or
- *   already claimed. ⛔ One sentence for that, naming no cause: the backend keeps the
- *   three indistinguishable on purpose.
+ *   grants }`, COUNTS — invitations now waiting for this account's answer, which
+ *   `useInvitations` lists and answers, and entities now shared with it — or `error`,
+ *   `kind: 'absent'` for a token unknown, revoked or already used. ⛔ One sentence for
+ *   that, naming no cause: the backend keeps them indistinguishable on purpose — and
+ *   it is not "no invitation": a member who confirmed the address the offer was sent to
+ *   holds its invitation already, and the link then answers `absent`.
  *
  * Once the backend has judged the token, its parameter leaves the address bar, so a
  * reload asks nothing again. `dismiss()` forgets the link without finishing it. On a
@@ -84,9 +86,16 @@ export function useMailedLink() {
     if (client?.enabled) setLink(mailedLink())
   }, [client])
 
+  // An offer waits for a session — so ask whether there is one, rather than wait for
+  // another component to.
+  const offer = link?.step === LINK.offer
+  useEffect(() => {
+    if (offer) client.ensureSession()
+  }, [client, offer])
+
   // An offer is claimed for whoever is signed in — and again, for another account.
   const signedIn = session?.status === 'authenticated' ? (session.viewer?.uuid ?? 'signed-in') : null
-  const claimant = link?.step === LINK.offer ? signedIn : null
+  const claimant = offer ? signedIn : null
   const finishes = !!link && (link.step === LINK.verify || claimant !== null)
 
   useEffect(() => {

package/src/index.js

@@ -23,6 +23,9 @@ export {
   confirmPasswordReset,
   verifyEmail,
   claimOffer,
+  listInvitations,
+  acceptInvitation,
+  declineInvitation,
   mailedLink,
   forgetMailedLink,
   readEntity,
@@ -40,6 +43,7 @@ export { useSignIn } from './hooks/useSignIn.js'
 export { useSignUp } from './hooks/useSignUp.js'
 export { usePasswordReset } from './hooks/usePasswordReset.js'
 export { useMailedLink } from './hooks/useMailedLink.js'
+export { useInvitations } from './hooks/useInvitations.js'
 export { useEntity } from './hooks/useEntity.js'
 export { useRecords } from './hooks/useRecords.js'
 export { useEntityWriter } from './hooks/useEntityWriter.js'

package/src/invitations.js

@@ -0,0 +1,91 @@
+/**
+ * Invitations — to join an organization of the site's backend, waiting for the
+ * member's answer.
+ *
+ * An invitation reaches a member two ways: sent to their account, it waits at once;
+ * sent to an address with no account here, it is an offer until the member claims it
+ * from its mailed link or confirms that address (`./mailed-links.js`). Either way it
+ * waits in one list, and is accepted or declined one by one. No React in this module;
+ * `useInvitations` is the hook over it.
+ *
+ * ⭐ **Functions of a client, not methods** — the page's client may have been created
+ * by an older copy of this package (`./mailed-links.js` says why). Everything here
+ * reaches the wire through `request` and keeps its state on the instance.
+ */
+
+import { ApiError } from './errors.js'
+import { INVITATION, INVITATIONS } from './wire.js'
+
+/** What the list is cached under — so a claim or an answer can drop it. */
+export const INVITATIONS_SPEC = Object.freeze({ endpoint: INVITATIONS.mine })
+
+/** Whether a cached read is the invitations list. */
+export const isInvitations = (spec) => spec?.endpoint === INVITATIONS.mine
+
+/**
+ * The invitations waiting for the signed-in account's answer — each as the backend
+ * lists it: `{ id, unit_uuid, unit_handle, unit_name, invited_by_account_id,
+ * created_at }`, `unit_handle` and `unit_name` possibly `null`.
+ *
+ * @param {object} client
+ * @param {{ signal?: AbortSignal }} [options]
+ * @returns {Promise<object[]>}
+ * @throws {ApiError} `auth` — nobody signed in
+ */
+export async function listInvitationsWith(client, { signal } = {}) {
+  const body = await client.request('GET', INVITATIONS.mine, { signal })
+  return Array.isArray(body?.[INVITATION.list]) ? body[INVITATION.list] : []
+}
+
+/**
+ * Accept an invitation — join the organization. The list is read again, and so is
+ * everything else the viewer has read, since what they may read can follow what they
+ * belong to (a list row's `via` can be `unit_member`); the session is asked again too,
+ * so whatever it carries is current.
+ *
+ * @param {object} client
+ * @param {number} id - the invitation's `id`, from the list
+ * @returns {Promise<object>} the backend's answer — the invitation, `status: 'accepted'`
+ * @throws {ApiError} `rule` — it no longer waits, and the list reads again · `absent` —
+ *   the id is not this account's to answer · `auth` — nobody signed in
+ */
+export async function acceptInvitationWith(client, id) {
+  const answer = await answered(client, INVITATIONS.accept(required(id, 'acceptInvitation')))
+  client.invalidate?.(() => true)
+  client.refresh?.()
+  return answer
+}
+
+/**
+ * Decline an invitation. The list is read again.
+ *
+ * @param {object} client
+ * @param {number} id - the invitation's `id`, from the list
+ * @returns {Promise<object>} the backend's answer — the invitation, `status: 'declined'`
+ * @throws {ApiError} as `acceptInvitationWith` does
+ */
+export async function declineInvitationWith(client, id) {
+  const answer = await answered(client, INVITATIONS.decline(required(id, 'declineInvitation')))
+  client.invalidate?.(isInvitations)
+  return answer
+}
+
+/**
+ * An answer, sent. ⭐ **One that no longer waits is still in the list this page holds**
+ * — answered in another tab, or withdrawn by its organization — so that refusal reads
+ * the list again, and the invitation leaves it. Which of those it was is the refusal's
+ * `detail`, for people; nothing here branches on it. Any other refusal leaves the cache.
+ */
+async function answered(client, route) {
+  try {
+    return await client.request('POST', route)
+  } catch (error) {
+    if (error?.status === INVITATION.notWaiting) client.invalidate?.(isInvitations)
+    throw error
+  }
+}
+
+function required(id, name) {
+  if (id == null || id === '') throw ApiError.invalid('No Invitation', `${name} needs the id of an invitation, from the list`)
+  return id
+}

package/src/mailed-links.js

@@ -14,6 +14,7 @@
 
 import { ApiError } from './errors.js'
 import { AUTH, CLAIM, LINK, OFFERS, PARAM } from './wire.js'
+import { isInvitations } from './invitations.js'
 
 const STEPS = Object.values(LINK)
 
@@ -75,20 +76,26 @@ export async function verifyEmailWith(client, token) {
 
 /**
  * Claim an offer with the token of its mailed link (`?offer=`), for the account signed
- * in. Answers counts (`CLAIM`): invitations now waiting for this account to accept, and
- * entities now shared with it — so when there are any, the viewer's cached reads go,
- * and what is mounted reads again.
+ * in. Answers counts (`CLAIM`): invitations now waiting for this account to answer
+ * (`./invitations.js`), and entities now shared with it — so the invitations list reads
+ * again when there are any of the first, and every cached read of the viewer's when
+ * there are any of the second.
+ *
+ * ⛔ **`absent` does not mean nothing is waiting.** A member who confirmed the address
+ * the offer was sent to holds what it bound already, and its token then answers
+ * `absent` like any other it cannot use.
  *
  * @param {object} client
  * @param {string} token
  * @returns {Promise<{ invitations: number, grants: number }>}
  * @throws {ApiError} `absent` — unknown, revoked or already claimed, one answer by design ·
- *   `auth` — nobody signed in
+ *   `auth` — nobody signed in, and the token is not spent
  */
 export async function claimOfferWith(client, token) {
   if (!token) throw ApiError.invalid('No Token', 'claimOffer needs the token of the mailed link')
   const answer = await client.request('POST', OFFERS.claim, { body: { [CLAIM.token]: token } })
-  if (answer?.[CLAIM.grants] > 0) client.invalidate?.(() => true)
+  const shared = answer?.[CLAIM.grants] > 0
+  if (shared || answer?.[CLAIM.invitations] > 0) client.invalidate?.((spec) => shared || isInvitations(spec))
   return answer
 }
 

package/src/mock/index.js

@@ -1,4 +1,4 @@
-import { AUTH, ENTITIES, MODELS, OFFERS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS, HANDOFF_REFUSAL } from '../wire.js'
+import { AUTH, ENTITIES, MODELS, OFFERS, INVITATIONS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS, HANDOFF_REFUSAL } from '../wire.js'
 import { MockStore, isUuid, refuse } from './store.js'
 import { DEFAULT_SEED } from './seed.js'
 
@@ -68,8 +68,10 @@ function adminPage(account) {
  * leaves an account unverified until its address is confirmed. The operator is the
  * account the backend's administration admits, so its Admin link answers — with a
  * redirect to a page of the mock's own, since the administration itself is not
- * modelled. It does not model entitlements behind `via`, nested sections, second
- * factors, password rules, or what an offer binds.
+ * modelled. An offer, claimed or bound by confirming its address, leaves its
+ * invitations waiting, each to answer once. It does not model entitlements behind
+ * `via`, nested sections, second factors, password rules, an offer's grants, what
+ * joining an organization gives, or an organization withdrawing an invitation.
  *
  * ## The mail it sends
  *
@@ -307,6 +309,25 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
       return fields(b, ['token'], '{"token": ...}') ?? answer(store.claimOffer(b.token))
     }
 
+    // ── Invitations ─────────────────────────────────────────────────────────
+    if (path === INVITATIONS.mine && method === 'GET') {
+      const bad = unexpected(q, [])
+      if (bad) return bad
+      if (!store.account) return unauthorized()
+      return json(200, store.invitationsOf(store.account))
+    }
+    const invitation = path.match(/^\/unit\/invitations\/([^/]+)\/[^/]+$/)
+    if (invitation && method === 'POST') {
+      const id = invitation[1]
+      const status = path === INVITATIONS.accept(id) ? 'accepted' : path === INVITATIONS.decline(id) ? 'declined' : null
+      if (status) {
+        const bad = unexpected(q, [])
+        if (bad) return bad
+        if (!store.account) return unauthorized()
+        return answer(store.answerInvitation(id, status))
+      }
+    }
+
     // ── A Model's definition ─────────────────────────────────────────────────
     if (path.startsWith(`${MODELS}/`) && method === 'GET') {
       const bad = unexpected(q, [])

package/src/mock/seed.js

@@ -15,7 +15,10 @@
  *   section's item, as the backend derives it.
  * - **`offers`** — optional, and none here: `{ email, invitations?, grants? }`, an
  *   invitation sent to an address with no account, mailed when the mock starts. Its
- *   link (`/?offer=…`) is how a site's pages are tried with one.
+ *   link (`/?offer=…`) is how a site's pages are tried with one. Claimed — or bound,
+ *   by signing up with that address and confirming it — it leaves `invitations`
+ *   waiting to be answered. One to an address a seeded account holds is that
+ *   account's from the start, and is not mailed: a way to open with one waiting.
  */
 export const DEFAULT_SEED = {
   accounts: [

package/src/mock/store.js

@@ -1,4 +1,4 @@
-import { CLAIM, FIELD, LINK, OP, PROBLEM } from '../wire.js'
+import { CLAIM, FIELD, INVITATION, LINK, OP, PROBLEM } from '../wire.js'
 import { checkItemWrite, OUTCOME } from './schema-shape.js'
 
 /**
@@ -25,6 +25,11 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  *   shared — a site runs third-party code with its member's session. *(Until
  *   2026-10-10 the operator's session held `system_admin` and read and wrote
  *   everything.)* A seeded account is the operator with `operator: true`.
+ * - **An offer binds when it is claimed, or when its address is confirmed** — and
+ *   then its token answers `404`, as an unknown one does (backend, 2026-10-11). What
+ *   it binds: its invitations, each waiting for the account's answer, to an
+ *   organization of its own with no handle and no name. A seeded offer to an address a
+ *   seeded account holds is bound to that account from the start, and is not mailed.
  *
  * ⛔ **Seeded fixtures plus in-memory mutation, and deliberately not a database.**
  * A mock that grows a schema and migrations becomes a second implementation that
@@ -32,9 +37,9 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  *
  * ⛔ **What it does not model**: entitlements behind `via` (a `via` read is the
  * same read), nested sections, second factors, reference fields, password rules,
- * and what an offer binds — a seeded offer answers the counts its seed gives, and
- * confirming the address it was sent to takes up nothing (the backend binds every
- * pending offer then).
+ * an offer's grants (a count, sharing nothing), what joining an organization
+ * gives — accepting an invitation answers, and opens nothing to read — and an
+ * organization withdrawing an invitation.
  */
 
 /** A mailed link — the site's root, the step's parameter, the token. */
@@ -131,13 +136,14 @@ export class MockStore {
    *   its members while their own records (progress, submissions) stay theirs alone.
    * @param {object[]} [seed.offers] - `{ email, invitations?, grants? }`: an invitation sent
    *   to an address with no account, mailed when the mock starts. Claiming it answers the
-   *   counts given (default `0`), once.
+   *   counts given (default `0`), once, and leaves that many invitations waiting. One to
+   *   an address a seeded account holds is that account's from the start.
    * @param {object} [options]
    * @param {string} [options.signedInAs] - start with this account already signed in.
    */
   constructor(seed = {}, { signedInAs = null } = {}) {
     this.clock = makeClock()
-    this.ids = { account: 1, model: 0, section: 0, entity: 0, item: 0 }
+    this.ids = { account: 1, model: 0, section: 0, entity: 0, item: 0, invitation: 0, unit: SITE_UNIT }
     this.accounts = []
     for (const a of seed.accounts || []) this.addAccount(a, { verified: true })
 
@@ -185,6 +191,8 @@ export class MockStore {
     this.pending = { verify: new Map(), reset: new Map() }
     /** Offers by token: `{ email, invitations, grants, claimed }`. */
     this.offers = new Map()
+    /** Invitations: `{ id, unit, invitedBy, to, status, createdAt, resolvedAt }` — `to` an account id. */
+    this.invitations = []
     for (const offer of seed.offers || []) this.addOffer(offer)
     this.entities = new Map()
     for (const e of seed.entities || []) this.seedEntity(e)
@@ -281,6 +289,8 @@ export class MockStore {
     if (!account) return refuse(400, 'Validation', 'invalid or expired verification token')
     this.pending.verify.delete(token)
     account.verified = true
+    // Every offer sent to the address it confirmed is the account's now — and its token spent.
+    for (const offer of this.offers.values()) if (!offer.claimed && offer.email === account.email) this.bind(offer, account)
     return { body: { verified: true } }
   }
 
@@ -306,7 +316,11 @@ export class MockStore {
 
   // ── Offers ──────────────────────────────────────────────────────────────────
 
-  /** An invitation to an address with no account here — its token mailed at once. */
+  /**
+   * An invitation to an address with no account here — its token mailed at once. To an
+   * address a verified account holds, it is bound to that account at once, as confirming
+   * the address would have bound it, and nothing is mailed.
+   */
   addOffer({ email, invitations = 0, grants = 0 } = {}) {
     const count = (n) => Number.isInteger(n) && n >= 0
     if (typeof email !== 'string' || !email || !count(invitations) || !count(grants)) {
@@ -315,22 +329,84 @@ export class MockStore {
       )
     }
     const token = newUuid()
-    this.offers.set(token, { email, invitations, grants, claimed: false })
-    this.outbox.push({ to: email, subject: "You've been invited", token, link: linkTo(LINK.offer, token) })
+    const offer = { email, invitations, grants, claimed: false }
+    this.offers.set(token, offer)
+    const holder = this.accounts.find((a) => a.email === email && a.verified)
+    if (holder) this.bind(offer, holder)
+    else this.outbox.push({ to: email, subject: "You've been invited", token, link: linkTo(LINK.offer, token) })
     return token
   }
 
   /**
-   * Claim an offer for the account signed in. Unknown, revoked and already claimed are
+   * Claim an offer for the account signed in. Unknown, revoked, claimed and bound are
    * one answer, `404`, as on the backend.
    */
   claimOffer(token) {
     const offer = this.offers.get(token)
     if (!offer || offer.claimed) return refuse(404, 'Not Found', 'offer not found')
-    offer.claimed = true
+    this.bind(offer, this.account)
     return { body: { [CLAIM.invitations]: offer.invitations, [CLAIM.grants]: offer.grants } }
   }
 
+  /** An offer becomes the account's: its token is spent, and its invitations wait. */
+  bind(offer, account) {
+    offer.claimed = true
+    for (let n = 0; n < offer.invitations; n += 1) {
+      this.invitations.push({
+        id: (this.ids.invitation += 1),
+        unit: { id: (this.ids.unit += 1), uuid: newUuid(), handle: null, name: null },
+        invitedBy: this.operator()?.id ?? null,
+        to: account.id,
+        status: 'pending',
+        createdAt: this.clock(),
+        resolvedAt: null,
+      })
+    }
+  }
+
+  // ── Invitations ─────────────────────────────────────────────────────────────
+
+  /** `GET /invitations/me` — the ones waiting for this account's answer, in the backend's shape. */
+  invitationsOf(account) {
+    return {
+      [INVITATION.list]: this.invitations
+        .filter((i) => i.to === account.id && i.status === 'pending')
+        .map((i) => ({
+          id: i.id,
+          unit_uuid: i.unit.uuid,
+          unit_handle: i.unit.handle,
+          unit_name: i.unit.name,
+          invited_by_account_id: i.invitedBy,
+          created_at: i.createdAt,
+        })),
+    }
+  }
+
+  /**
+   * Accept or decline an invitation waiting for the account signed in — `accepted` or
+   * `declined` — as the backend answers (2026-10-12): `404` for an id that is not this
+   * account's to answer, unknown or another's alike, and `409` for one of its own that
+   * no longer waits, its `detail` naming what it became.
+   */
+  answerInvitation(id, status) {
+    const invitation = this.invitations.find((i) => String(i.id) === String(id) && i.to === this.account?.id)
+    if (!invitation) return refuse(404, 'Not Found', `invitation ${id} not found`, { kind: 'invitation', key: String(id) })
+    if (invitation.status !== 'pending') return refuse(INVITATION.notWaiting, 'Conflict', `this invitation was already ${invitation.status}`)
+    invitation.status = status
+    invitation.resolvedAt = this.clock()
+    return {
+      body: {
+        id: invitation.id,
+        unit_id: invitation.unit.id,
+        to_account_id: invitation.to,
+        invited_by: invitation.invitedBy,
+        status,
+        created_at: invitation.createdAt,
+        resolved_at: invitation.resolvedAt,
+      },
+    }
+  }
+
   // ── Models ──────────────────────────────────────────────────────────────────
 
   defineModel(name, decl = {}, itemSections = new Set()) {

package/src/wire.js

@@ -49,7 +49,13 @@
  * `/sites/*`. Those routes create sites, which is the app's job, not a
  * foundation's, and a site's own `backend` service has no site to address.
  *
- * ⛔ Do not add a route that is not under `/entities`, `/models` or `/auth`.
+ * Its routes are under `/entities`, `/models` and `/auth`, plus what a member does
+ * with an invitation — claim an offer (`OFFERS`), answer an invitation
+ * (`INVITATIONS`) — the steps the backend's mail asks a member to finish on the site
+ * (2026-10-11). ⛔ Never `/sites/*`, and nothing that administers: the backend's
+ * administration is reached through the Admin link (`AUTH.memberHandoff`), never
+ * wrapped. *(This said "no route that is not under `/entities`, `/models` or
+ * `/auth`" until 2026-10-11.)*
  */
 export const ENTITIES = '/entities'
 
@@ -92,11 +98,13 @@ export const AUTH = {
   register: '/auth/register',
   /**
    * `GET /auth/verify?token=` → `{ verified: true }`: the address is confirmed and the
-   * member may sign in — it starts no session. A token that was used, has expired or
-   * was never valid is `400 Validation`. The token comes from the link the backend
-   * mails, which lands on the site's root (`LINK.verify`), and `verifyEmail` finishes
-   * it. *(Until 2026-10-11 that link named the backend's own sign-in page, and this
-   * package did not call the route.)*
+   * member may sign in — it starts no session — and every offer sent to that address
+   * binds to the account, its invitations waiting (`OFFERS`, `INVITATIONS`; MEASURED by
+   * backend, 2026-10-11). A token that was used, has expired or was never valid is
+   * `400 Validation`. The token comes from the link the backend mails, which lands on
+   * the site's root (`LINK.verify`), and `verifyEmail` finishes it. *(Until 2026-10-11
+   * that link named the backend's own sign-in page, and this package did not call the
+   * route.)*
    */
   verify: '/auth/verify',
   resetRequest: '/auth/reset/request',
@@ -181,7 +189,7 @@ export const LINK = {
 }
 
 /**
- * Offers. **MEASURED** by backend, 2026-09-15.
+ * Offers. **MEASURED** by backend, 2026-09-15 and 2026-10-11.
  *
  * Inviting an address nobody here holds — to an organization, or to share an entity —
  * mints an offer, and the backend mails its token to that address (`LINK.offer`).
@@ -189,10 +197,18 @@ export const LINK = {
  * account's own address — and what the offer held binds to it.
  *
  * `POST /offers/claim` `{ token }` → `200 { invitations, grants }` (`CLAIM`) —
- * COUNTS, not names: invitations now waiting for this account to accept, and entities
- * now shared with it. ⛔ **An unknown, revoked or already-claimed token is ONE answer,
- * `404`**, so the route never says whether a token was ever real. A missing `token`
- * is `400`.
+ * COUNTS, not names: invitations now waiting for this account to answer
+ * (`INVITATIONS`), and entities now shared with it, live at once. ⛔ **An unknown,
+ * revoked or already-claimed token is ONE answer, `404`**, so the route never says
+ * whether a token was ever real. A missing `token` is `400`.
+ *
+ * - **With no session, `401 { status: 401, title: 'Unauthorized' }`, and the token is
+ *   not spent** — the same link works once someone signs in (2026-10-11).
+ * - **The token is spent by the claim — or earlier, by the member confirming the
+ *   address the offer was sent to** (`AUTH.verify`), which binds the offer to that
+ *   account. From then on it answers `404`, as an unknown token does — even to the
+ *   account that holds what it bound (2026-10-11). ⇒ A `404` on a claim does not mean
+ *   no invitation is waiting: list them.
  */
 export const OFFERS = {
   claim: '/offers/claim',
@@ -205,6 +221,48 @@ export const CLAIM = {
   grants: 'grants',
 }
 
+/**
+ * Invitations to join an organization — a unit, in the backend's word — waiting for the
+ * member's answer. **MEASURED** by backend, 2026-10-11 and 2026-10-12.
+ *
+ * One sent to an address with no account here is an offer until it is claimed or its
+ * address confirmed (`OFFERS`); one sent to an account is waiting at once, and its mail
+ * is the site's root with no parameter — the member signs in (`LINK`). Either way it
+ * waits here, and the claim's answer names none of them, so the list is how a member
+ * area finds one:
+ *
+ * | route | answer |
+ * |---|---|
+ * | `GET /invitations/me` | `{ invitations: [{ id, unit_uuid, unit_handle, unit_name, invited_by_account_id, created_at }] }` — `id` an integer; `unit_handle` and `unit_name` may be `null`. **Only the invitations still waiting**: one answered, or withdrawn by its organization, leaves the list, which is why a row carries no status. With no session, `401 { status: 401, title: 'Unauthorized' }` |
+ * | `POST /unit/invitations/{id}/accept` | `{ id, unit_id, to_account_id, invited_by, status: 'accepted', created_at, resolved_at }` |
+ * | `POST /unit/invitations/{id}/decline` | the same row, `status: 'declined'` |
+ *
+ * Both answers are sent with no body, as the backend's tests send them. Two refusals:
+ *
+ * - **`404 Not Found` + `kind: 'invitation'`, `key`** — the id is not this account's to
+ *   answer: unknown, or another account's, one answer by design.
+ * - **`409 Conflict` (`INVITATION.notWaiting`)** — it no longer waits: this account
+ *   answered it, or its organization withdrew it. Its `detail` names what it became —
+ *   `this invitation was already accepted` (`declined`, `revoked`) — and is for people:
+ *   ⛔ branch on the status, never the detail. It carries no `current_updated_at`, so
+ *   its kind is `rule` (`./errors.js`): the same answer fails the same way again.
+ */
+export const INVITATIONS = {
+  mine: '/invitations/me',
+  accept: (id) => `/unit/invitations/${segment(id)}/accept`,
+  decline: (id) => `/unit/invitations/${segment(id)}/decline`,
+}
+
+/**
+ * The list's key — all this package reads of an answer here, since the rows go to the
+ * caller as they are — and the status of an answer to an invitation that no longer
+ * waits. MEASURED.
+ */
+export const INVITATION = {
+  list: 'invitations',
+  notWaiting: 409,
+}
+
 /** A sign-in that needs a second factor. MEASURED. */
 export const TOTP = {
   status: 'totp_required',
@@ -506,6 +564,7 @@ export const SCHEMA = {
  * | answer | means |
  * |---|---|
  * | `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 Conflict`, no token | an invitation that no longer waits — answered, or withdrawn (`INVITATIONS`, 2026-10-12) |
  * | `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) |
@@ -526,22 +585,18 @@ export const PROBLEM = {
  * ⛔ 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.
  *
- * Empty from 2026-09-18 to 2026-10-11, when the last two were answered by measurement:
+ * Retired by measurement:
  *
  * | retired | answered as |
  * |---|---|
- * | `viewer-unit-signal` | ⛔ false — every member of a site acts in the same unit; see `VIEWER` |
- * | `via-and-depth-compose` | ✅ true — see `PARAM` |
+ * | `viewer-unit-signal` | ⛔ false — every member of a site acts in the same unit; see `VIEWER` (2026-09-18) |
+ * | `via-and-depth-compose` | ✅ true — see `PARAM` (2026-09-18) |
+ * | `offer-claim-needs-a-session` | ✅ true — `401` with no session, and the token is not spent; see `OFFERS` (2026-10-11) |
+ * | `invitations-list-holds-the-waiting` | ✅ true — only the invitations still waiting, and `401` with no session; see `INVITATIONS` (2026-10-12) |
+ * | `invitation-answer-refusals` | ⚠️ half — decline answers as the mock did, but one that no longer waits is `409`, not the `404` an id not this account's gets; see `INVITATIONS` (2026-10-12) |
  *
  * *(Retired 2026-09-17: `write-response-fields`, `move-exists`, `move-position`,
  * `op-field-names` — see `FIELD` and `OP`.)* A new entry needs `we`, `from` and
  * `breaks`; `tests/wire.test.js` pins the set, so adding one is deliberate.
  */
-export const ASSUMPTIONS = [
-  {
-    id: 'offer-claim-needs-a-session',
-    we: 'claim an offer only once signed in (`useMailedLink`), and answer a claim with no session `401` in the mock',
-    from: 'the backend: the member signs up or signs in, then claims (2026-10-11). Nobody has recorded what a claim with no session answers',
-    breaks: 'nothing the hook does, since it never claims signed out — but the mock would answer a signed-out claim unlike the backend',
-  },
-]
+export const ASSUMPTIONS = []