@uniweb/api 0.6.9 → 0.7.0

package/README.md

@@ -1,10 +1,10 @@
 # @uniweb/api
 
-The client a foundation uses to talk to **its site's `api` service** — sign-in, the
+The client a foundation uses to talk to **its site's `backend` service** — sign-in, the
 site's members, and the content they create.
 
 You import it the way you import `@uniweb/kit`. It is bundled into your foundation,
-tree-shaken, and **inert on a site that has no `api` service**: nothing throws, no request
+tree-shaken, and **inert on a site that has no `backend` service**: nothing throws, no request
 leaves, and your components render the version of themselves that does not need one.
 
 ```bash
@@ -17,9 +17,9 @@ Ask before you draw. This is a synchronous read of the site's own configuration,
 a probe — there is nothing to await.
 
 ```jsx
-import { isApiEnabled } from '@uniweb/kit'
+import { isBackendEnabled } from '@uniweb/kit'
 
-if (!isApiEnabled()) return <StaticVersion />
+if (!isBackendEnabled()) return <StaticVersion />
 ```
 
 ⛔ **And when the answer is no, draw nothing** — not a disabled button, and not an
@@ -79,7 +79,7 @@ const { status, records, hasMore } = useRecords({ schema: '@acme/session', scope
 ```
 
 ⭐ **`absent` and an empty `ready` are different answers.** `absent` means there is no
-live source — no `api` service, or nobody signed in — so render your site's own content.
+live source — no `backend` service, or nobody signed in — so render your site's own content.
 `ready` with `records: []` means the service answered and there is nothing there.
 Showing "nothing yet" for the first case tells a visitor their content is missing
 when it is simply not being asked for.
@@ -170,8 +170,9 @@ Building against a live service is slow and puts a shared database behind your
 experiments. Name a local one in `site.yml`:
 
 ```yaml
-api: /_api                 # where the service answers — the same in production
-$devApi: ./mock/api.js     # what answers it locally; never published
+services:
+  backend: true                # ask your host for it, on a site you publish
+$devBackend: ./mock/api.js    # what answers it in `uniweb dev`; never published
 ```
 
 ```js
@@ -203,8 +204,9 @@ export default createMockBackend({
 }).fetch
 ```
 
-`uniweb dev` mounts it at your `api:` address — same origin, so cookies behave as they
-will in production, and your site's configuration is identical either way.
+`uniweb dev` mounts it at an address of its own on the dev server, and hands your site that
+address the way a host hands over its own — same origin, so cookies behave as they will in
+production, and nothing in your site's configuration changes between the two.
 
 ⭐ **The mock answers what the backend answers** — the same statuses, bodies and
 refusals, for every route this package uses. It enforces what your schemas declare —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.6.9",
+  "version": "0.7.0",
   "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.36.0"
+    "@uniweb/core": "^0.38.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/client.js

@@ -2,7 +2,7 @@
  * @uniweb/api — the client half. No React in this module.
  *
  * A foundation's client for the site's own backend — the one a host declares
- * as the site service `api`. Absent that declaration the site has no such
+ * as the site service `backend`. Absent that declaration the site has no such
  * backend and everything here is inert: no request leaves, and a component
  * renders for that state rather than retrying it.
  *
@@ -18,8 +18,16 @@ import { composeUrl, isCrossOrigin, readBody, UNSAFE } from './http.js'
 import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA, PAGE, TOTP } from './wire.js'
 import { Ledger } from './ledger.js'
 
-/** The site service this package reads its base from — the only name it owns. */
-export const SERVICE_NAME = 'api'
+/**
+ * The site service this package reads its base from — the only name it owns.
+ *
+ * ⛔ **It was `api` until 2026-10-07.** A service is named for what it gives the
+ * site — `search`, `records` — and this one is the site's own backend; `/api` is
+ * only the interface it answers on, which is what this package is named for. A
+ * foundation built before then asks for `api`, which no host offers now, and draws
+ * no sign-in until it is rebuilt.
+ */
+export const SERVICE_NAME = 'backend'
 
 /**
  * The shape of the shared instance, as a contract between copies of this
@@ -31,10 +39,10 @@ export const CONTRACT = 1
 /**
  * Where the site's backend is, if it has one.
  *
- * `resolveService` answers with the host's offer first (`config.services.api`),
- * then the site's own declaration (`api:` in `site.yml`), and `null` when neither
- * names an address. Absence is the ordinary state of a site with no backend,
- * not an error.
+ * `resolveService` answers with the host's offer first (`config.services.backend`),
+ * then the site's own address (`backend:` under `services:` in `site.yml`), and
+ * `null` when neither names one. Absence is the ordinary state of a site with no
+ * backend, not an error.
  *
  * @param {object} website - the active Website, or anything shaped `{ config, basePath }`
  * @returns {string|null} the base every request is made against, or null
@@ -44,34 +52,35 @@ export function resolveBase(website) {
 }
 
 /**
- * Does this site have an app backend — the `api` service?
+ * Does this site have an app backend — the `backend` service?
  *
  * The question to ask before drawing a sign-in affordance or any control only a
  * backend can answer. False means: draw nothing, or the static alternative the
  * site already carries.
  *
  * ⭐ **The website argument is OPTIONAL and defaults to the active one**, so this
- * is the same call as `@uniweb/kit`'s `isApiEnabled()` — one predicate per
+ * is the same call as `@uniweb/kit`'s `isBackendEnabled()` — one predicate per
  * service, no arguments, the website resolved for you. Pass one explicitly only
  * when you already hold it, or are working outside a render.
  *
  * ⛔ **THE DEFAULT IS NOT A CONVENIENCE, IT CLOSES A TRAP.** For one commit this
  * took a REQUIRED website while every doc and template showed the no-argument
- * spelling — so `import { isApiEnabled } from '@uniweb/api'` followed by
- * `isApiEnabled()` resolved `undefined`, returned `false` forever, and drew no
- * sign-in UI on a site that had a backend. Silent, and indistinguishable from a
- * site with no backend: exactly the invisible absence this predicate exists to
- * prevent. Caught in review the same day; pinned by `tests/enabled.test.js`.
+ * spelling — so the documented call resolved `undefined`, returned `false`
+ * forever, and drew no sign-in UI on a site that had a backend. Silent, and
+ * indistinguishable from a site with no backend: exactly the invisible absence
+ * this predicate exists to prevent. Caught in review the same day; pinned by
+ * `tests/enabled.test.js`.
  *
- * ⛔ **Renamed from `isEnabled` (2026-09-10).** The old name said nothing about
- * its subject and collided with three unrelated `isEnabled`s in the framework —
- * including the field `useSearch()` returns, which made `uniweb doctor` read a
- * search control as gated when it was gated on this instead.
+ * ⛔ **Renamed twice.** From `isEnabled` (2026-09-10): the old name said nothing
+ * about its subject and collided with three unrelated `isEnabled`s in the
+ * framework — including the field `useSearch()` returns, which made `uniweb
+ * doctor` read a search control as gated when it was gated on this instead. Then
+ * from `isApiEnabled` (2026-10-07), with the service it asks about (`SERVICE_NAME`).
  *
  * @param {object} [website] - defaults to the active website
  * @returns {boolean}
  */
-export function isApiEnabled(website = getUniweb()?.activeWebsite ?? null) {
+export function isBackendEnabled(website = getUniweb()?.activeWebsite ?? null) {
   return resolveBase(website) !== null
 }
 

package/src/hooks/useRecords.js

@@ -18,7 +18,7 @@ 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 for this viewer** — a site with no
- * `api` service, which is the ordinary standalone case, or nobody signed in, since
+ * `backend` 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.**

package/src/index.js

@@ -13,7 +13,7 @@
 export {
   SERVICE_NAME,
   resolveBase,
-  isApiEnabled,
+  isBackendEnabled,
   probeSession,
   signIn,
   completeChallenge,

package/src/mock/index.js

@@ -3,7 +3,7 @@ import { MockStore, isUuid, refuse } from './store.js'
 import { DEFAULT_SEED } from './seed.js'
 
 /**
- * A mock of a site's `api` service, for local development.
+ * A mock of a site's `backend` service, for local development.
  *
  * ```js
  * import { createMockBackend } from '@uniweb/api/mock'
@@ -29,7 +29,7 @@ import { DEFAULT_SEED } from './seed.js'
  * ## Where it answers
  *
  * Its routes are the API's own — `/auth/me`, `/entities` — under whatever the
- * site's `api` address is. It accepts a request with the site's `/_api` prefix
+ * site's `backend` address is. It accepts a request with the site's `/_api` prefix
  * still on, and one with an extra `/api` after it (how clients before 0.4
  * composed URLs), so it answers the same whether or not the server mounting it
  * strips its path.

package/src/mock/node.js

@@ -40,7 +40,7 @@ async function send(response, res) {
 
 /**
  * Connect-style middleware — what Vite's `configureServer` takes. Mount it at the
- * site's `api` address (`/_api`), which is the base the client composes routes
+ * site's `backend` address (`/_api`), which is the base the client composes routes
  * onto: `/_api/auth/me`, `/_api/entities`.
  *
  * ```js
@@ -76,7 +76,7 @@ export function middleware(mock, { prefix = '/_api' } = {}) {
 
 /**
  * A standalone server. Resolves once listening; call `close()` to stop. Its routes
- * answer at the root — a site's `api` address for it is the server's URL
+ * answer at the root — a site's `backend` address for it is the server's URL
  * (`http://localhost:8787`), plus `prefix` when one is given.
  *
  * @param {{ fetch: Function }} mock

package/src/mock/store.js

@@ -6,7 +6,7 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  * entities whose content is items.
  *
  * ⭐ **It stores what the backend stores, the way the backend stores it** —
- * measured 2026-09-18 against a real one set up as a site's `api` service:
+ * measured 2026-09-18 against a real one set up as a site's `backend` service:
  *
  * - **An entity's content is items, each in a section of its Model.** There is no
  *   entity-level data. A `single` section holds one item; its `brief` section's item

package/src/wire.js

@@ -22,7 +22,7 @@
  * ## ⭐ MEASURED 2026-09-18 — every shape below, in literal responses
  *
  * The whole surface this package touches was exercised against a real backend set
- * up the way a site's `api` service is: one operator account, members who sign up
+ * up the way a site's `backend` service is: one operator account, members who sign up
  * themselves, and the site's own Models. Where this module quotes a shape it was
  * copied from a response, not described. That pass corrected the package in these
  * places, each now fixed and pinned by a test:
@@ -47,7 +47,7 @@
  * The lane. ⭐ **RULED** *(2026-09-01)*: this package reads and writes
  * **entities**, reads the definitions of their Models, and touches nothing under
  * `/sites/*`. Those routes create sites, which is the app's job, not a
- * foundation's, and a site's own `api` service has no site to address.
+ * 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`.
  */
@@ -59,7 +59,7 @@ export const MODELS = '/models'
 /**
  * The base, and how a route joins it. **MEASURED.**
  *
- * The base the site is handed for its `api` service is the address of the
+ * The base the site is handed for its `backend` service is the address of the
  * backend's API route space, and every route here is relative to it:
  * `${base}/auth/me`, `${base}/entities`. On a hosted site that is `/_api` on the
  * site's own origin, which reaches the backend's `/api/…`; wherever a page reaches
@@ -138,7 +138,7 @@ export const TOTP = {
  * `unit_admin`, `content_editor`, `user`. An ordinary member holds none: `[]`.
  *
  * `workspace` is `{ unit_uuid, handle }` — **the workspace the request works in**. This
- * package's requests name none, and on a site's `api` service such a request lands in
+ * package's requests name none, and on a site's `backend` service such a request lands in
  * the service's **home org**, `handle: 'home'`, in which every account is enrolled.
  * Both `null` there means an account that is not a member — a service account, a
  * revoked membership. (On a backend with no home org, naming none is personal: both