@uniweb/api 0.1.0

package/src/hooks/useEntity.js

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react'
+import { getClient } from '../client.js'
+
+const noSubscribe = () => () => {}
+const noSnapshot = () => null
+const DISABLED = Object.freeze({ status: 'absent', entity: null, error: null })
+
+/**
+ * One entity by id — through a container the viewer holds an entitlement on,
+ * when `via` names one.
+ *
+ * ```jsx
+ * const { status, entity } = useEntity({ schema: '@/lesson', uuid, via: course.uuid })
+ * // status: 'loading' | 'ready' | 'absent' | 'error'
+ * if (status === 'absent') return <EnrolWall />   // not found OR not permitted — one word, by design
+ * ```
+ *
+ * Cached in the site's data store under a key scoped to the viewer, so a
+ * sign-in or sign-out changes the key and the record is read again for who
+ * is now looking. On a site with no backend the answer is `absent`: there is
+ * nothing to read.
+ *
+ * @param {{ schema: string, uuid: string, via?: string } | null} ref - pass null to skip
+ * @returns {{ status: string, entity: object|null, error: Error|null, refresh: Function }}
+ */
+export function useEntity(ref) {
+  const client = getClient()
+  const website = client?.website ?? null
+  const store = website?.dataStore ?? null
+
+  // Re-key on a viewer change: the session is part of the key.
+  useSyncExternalStore(
+    client ? client.subscribe : noSubscribe,
+    client ? () => client.session : noSnapshot,
+    client ? () => client.session : noSnapshot,
+  )
+
+  const active = !!(client && client.enabled && store && ref && ref.uuid)
+  const key = active
+    ? client.cacheKey({ endpoint: `/entities/${ref.uuid}`, schema: ref.schema, via: ref.via })
+    : 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)
+
+  useEffect(() => {
+    if (!key || entry) return undefined
+    let live = true
+    setError(null)
+    client.load(key, () => client.readEntity(ref)).catch((err) => {
+      if (live) setError(err)
+    })
+    return () => {
+      live = false
+    }
+    // `ref` is read through `key`, which already encodes schema, uuid and via.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [client, key, entry, attempt])
+
+  const refresh = useCallback(() => {
+    if (key && store) store.delete(key)
+    setAttempt((n) => n + 1)
+  }, [store, key])
+
+  if (!active) return { ...DISABLED, refresh }
+  if (entry) return { status: entry.data.status, entity: entry.data.entity, error: null, refresh }
+  if (error) return { status: 'error', entity: null, error, refresh }
+  return { status: 'loading', entity: null, error: null, refresh }
+}
+
+export default useEntity

package/src/hooks/usePasswordReset.js

@@ -0,0 +1,30 @@
+import { useCallback } from 'react'
+import { getClient } from '../client.js'
+import { ApiError } from '../errors.js'
+import { useAction } from './useAction.js'
+
+/**
+ * Password reset in two steps: `request(fields)` asks for one — the backend
+ * answers `202` whether or not the account exists, deliberately — and
+ * `confirm(fields)` completes it with the token the viewer received. One
+ * lifecycle covers whichever step ran last.
+ *
+ * @returns {{ request: Function, confirm: Function, status: string, error: Error|null, response: any, reset: Function }}
+ */
+export function usePasswordReset() {
+  const client = getClient()
+  const { run, status, error, response, reset } = useAction(
+    useCallback(
+      (step, fields) => {
+        if (!client) throw ApiError.disabled()
+        return step === 'confirm' ? client.confirmPasswordReset(fields) : client.requestPasswordReset(fields)
+      },
+      [client],
+    ),
+  )
+  const request = useCallback((fields) => run('request', fields), [run])
+  const confirm = useCallback((fields) => run('confirm', fields), [run])
+  return { request, confirm, status, error, response, reset }
+}
+
+export default usePasswordReset

package/src/hooks/useSession.js

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useSyncExternalStore } from 'react'
+import { getClient } from '../client.js'
+
+const NONE = Object.freeze({ status: 'anonymous', viewer: null, error: null })
+const noSubscribe = () => () => {}
+const noSnapshot = () => NONE
+const noop = async () => NONE
+
+/**
+ * The viewer's session.
+ *
+ * `status` is `anonymous` synchronously on a site that declares no backend —
+ * the ordinary case — and `loading` on one that does, until the backend has
+ * answered. `canSignIn` is false when there is nothing to sign in to: draw no
+ * affordance on false. `error` is set when the backend could not be asked;
+ * `refresh()` asks again.
+ *
+ * Reads the shared snapshot through `useSyncExternalStore`, so every copy of
+ * this package on the page sees one session, and the first render on the
+ * server matches the first render in the browser.
+ *
+ * @returns {{
+ *   status: 'loading' | 'anonymous' | 'authenticated',
+ *   viewer: object | null,
+ *   error: Error | null,
+ *   canSignIn: boolean,
+ *   signOut: () => Promise<void>,
+ *   refresh: () => Promise<object>,
+ * }}
+ */
+export function useSession() {
+  const client = getClient()
+  const session = useSyncExternalStore(
+    client ? client.subscribe : noSubscribe,
+    client ? () => client.session : noSnapshot,
+    client ? () => client.session : noSnapshot,
+  )
+
+  useEffect(() => {
+    if (client && client.enabled) client.ensureSession()
+  }, [client])
+
+  const signOut = useCallback(() => (client ? client.signOut() : noop()), [client])
+  const refresh = useCallback(() => (client ? client.refresh() : noop()), [client])
+
+  return {
+    status: session.status,
+    viewer: session.viewer,
+    error: session.error,
+    canSignIn: !!(client && client.enabled),
+    signOut,
+    refresh,
+  }
+}
+
+export default useSession

package/src/hooks/useSignIn.js

@@ -0,0 +1,54 @@
+import { useCallback, useState } from 'react'
+import { getClient } from '../client.js'
+import { ApiError } from '../errors.js'
+import { useAction } from './useAction.js'
+
+/**
+ * Sign in, with the second factor parked as a `challenge` when the backend
+ * asks for one.
+ *
+ * ```jsx
+ * const { signIn, completeChallenge, status, error, challenge, canSignIn } = useSignIn()
+ * if (!canSignIn) return null
+ * // status: 'idle' | 'submitting' | 'success' | 'error'
+ * // challenge: null | { kind: 'totp' } — render the code field and call completeChallenge(code)
+ * ```
+ *
+ * The credentials object goes to the backend as the request body, unchanged.
+ * A refused credential is an `ApiError` with `kind: 'auth'`.
+ */
+export function useSignIn() {
+  const client = getClient()
+  const [challenge, setChallenge] = useState(null)
+
+  const { run, status, error, reset: resetAction } = useAction(
+    useCallback(
+      async (step, arg) => {
+        if (!client) throw ApiError.disabled()
+        const result = step === 'challenge' ? await client.completeChallenge(arg) : await client.signIn(arg)
+        setChallenge(result.ok ? null : (result.challenge ?? null))
+        return result
+      },
+      [client],
+    ),
+  )
+
+  const signIn = useCallback((credentials) => run('credentials', credentials), [run])
+  const completeChallenge = useCallback((code) => run('challenge', code), [run])
+  const reset = useCallback(() => {
+    setChallenge(null)
+    resetAction()
+  }, [resetAction])
+
+  return {
+    signIn,
+    completeChallenge,
+    status,
+    error,
+    challenge,
+    canSignIn: !!(client && client.enabled),
+    reset,
+  }
+}
+
+export default useSignIn

package/src/hooks/useSignUp.js

@@ -0,0 +1,28 @@
+import { useCallback } from 'react'
+import { getClient } from '../client.js'
+import { ApiError } from '../errors.js'
+import { useAction } from './useAction.js'
+
+/**
+ * Sign up. The fields object goes to the backend as the request body,
+ * unchanged. The backend answers `202`: the account is inert until the viewer
+ * verifies it, so `status: 'success'` means "check your email", and that copy
+ * is the foundation's to write.
+ *
+ * @returns {{ signUp: Function, status: string, error: Error|null, response: any, canSignUp: boolean, reset: Function }}
+ */
+export function useSignUp() {
+  const client = getClient()
+  const { run, status, error, response, reset } = useAction(
+    useCallback(
+      (fields) => {
+        if (!client) throw ApiError.disabled()
+        return client.signUp(fields)
+      },
+      [client],
+    ),
+  )
+  return { signUp: run, status, error, response, canSignUp: !!(client && client.enabled), reset }
+}
+
+export default useSignUp

package/src/http.js

@@ -0,0 +1,82 @@
+/**
+ * The wire, below the client: URL composition, credentials, body reading.
+ * Pure functions; the client calls them and nothing else does.
+ */
+
+const ABSOLUTE_URL_RE = /^[a-z][a-z0-9+.-]*:/i
+
+/** Methods that carry a body, or change state — the ones the CSRF header rides on. */
+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
+ * 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.
+ *
+ * @param {string} base
+ * @returns {boolean}
+ */
+export function isCrossOrigin(base) {
+  if (!ABSOLUTE_URL_RE.test(base)) return false
+  const origin = globalThis.location?.origin
+  if (!origin) return true
+  try {
+    return new URL(base).origin !== origin
+  } catch {
+    return true
+  }
+}
+
+/**
+ * `${base}/api${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.
+ * `null` and `undefined` query values are omitted.
+ *
+ * @param {string} base
+ * @param {string} path - the route, with or without a leading slash
+ * @param {object} [query]
+ * @returns {string}
+ */
+export function composeUrl(base, path, query) {
+  const root = base.replace(/\/+$/, '')
+  const p = path.startsWith('/') ? path : `/${path}`
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value === undefined || value === null) continue
+    params.set(key, String(value))
+  }
+  const qs = params.toString()
+  return `${root}/api${p}${qs ? `?${qs}` : ''}`
+}
+
+/**
+ * The parsed body of a response: JSON when the response says so, `null` on
+ * `204`, and `{ detail: text }` for a non-JSON body so a refusal without
+ * problem-JSON still carries what the server said.
+ *
+ * @param {Response} res
+ * @returns {Promise<*>}
+ */
+export async function readBody(res) {
+  if (res.status === 204) return null
+  const type = res.headers?.get?.('content-type') || ''
+  if (/json/i.test(type)) {
+    try {
+      return await res.json()
+    } catch {
+      return null
+    }
+  }
+  try {
+    const text = await res.text()
+    return text ? { detail: text } : null
+  } catch {
+    return null
+  }
+}

package/src/index.js

@@ -0,0 +1,34 @@
+/**
+ * @uniweb/api
+ *
+ * A foundation's client for the site's own backend: session, records,
+ * entities, writes — in the site's vocabulary, never in routes. Imported the
+ * way `@uniweb/kit` is, bundled into the foundation, inert on a site that
+ * declares no backend.
+ *
+ * This entry carries the React hooks and the headless gates.
+ * `@uniweb/api/client` carries the plain functions and imports no React.
+ */
+
+export {
+  SERVICE_NAME,
+  resolveBase,
+  isEnabled,
+  probeSession,
+  signIn,
+  completeChallenge,
+  signOut,
+  signUp,
+  requestPasswordReset,
+  confirmPasswordReset,
+  readEntity,
+  ApiError,
+  Ledger,
+} from './client.js'
+
+export { useSession } from './hooks/useSession.js'
+export { useSignIn } from './hooks/useSignIn.js'
+export { useSignUp } from './hooks/useSignUp.js'
+export { usePasswordReset } from './hooks/usePasswordReset.js'
+export { useEntity } from './hooks/useEntity.js'
+export { SignedIn, SignedOut } from './components/gates.js'

package/src/ledger.js

@@ -0,0 +1,97 @@
+/**
+ * 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 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.
+ *
+ * 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.
+ *
+ * Two field names are read from responses — the item's id and its
+ * `item_updated_at` — and the first of those is a reading of the design, not
+ * yet a pinned wire fact. It is one constant.
+ */
+
+const ID_FIELDS = ['item', 'item_id', 'id']
+
+function itemIdOf(record) {
+  for (const field of ID_FIELDS) {
+    if (record?.[field] != null) return String(record[field])
+  }
+  return null
+}
+
+export class Ledger {
+  constructor() {
+    this._at = new Map()
+  }
+
+  /** Record an item's token, from a read or a write response. */
+  note(itemId, updatedAt) {
+    if (itemId == null || updatedAt == null) return
+    this._at.set(String(itemId), updatedAt)
+  }
+
+  /** The last-seen token for an item, or null when none was recorded. */
+  get(itemId) {
+    return this._at.get(String(itemId)) ?? null
+  }
+
+  forget(itemId) {
+    this._at.delete(String(itemId))
+  }
+
+  /**
+   * 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
+   * @returns {object} the op, with `if_unmodified_since` when known
+   */
+  stamp(op) {
+    if (!op || op.kind === 'create' || op.item == null) return op
+    const at = this.get(op.item)
+    return at == null ? op : { ...op, if_unmodified_since: at }
+  }
+
+  /**
+   * 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.
+   *
+   * @param {object} result
+   */
+  absorb(result) {
+    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 || !('item_updated_at' in result)) return
+    if (result.item_updated_at === null) this.forget(id)
+    else this.note(id, result.item_updated_at)
+  }
+
+  /**
+   * On a `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
+   * @param {{ extensions?: { current_updated_at?: * } }} error
+   * @returns {boolean} whether a token was recorded
+   */
+  rebase(itemId, error) {
+    const current = error?.extensions?.current_updated_at
+    if (current == null) return false
+    this.note(itemId, current)
+    return true
+  }
+}