okengine 0.18.4 → 0.19.0

package/site/content/docs/client/live.mdx

@@ -0,0 +1,234 @@
+---
+title: "Live"
+description: "api.live SSE subscribe, exposure matching, resume gaps, and live resource queries."
+icon: "Activity"
+source: "docs/spec/unified-theory.md"
+---
+
+`signal.live` is HTTP SSE. Expose with `.live(signal)` on GET (or `http.live(signal)` for
+`GET /_oke/live/{name}`), then subscribe with a callback. `for await` stays on the server.
+
+For developers streaming shipment status, checkout progress, or live inbox rows into a browser or
+ops console.
+
+<Callout title="The one rule">
+  Subscribe with a callback and an unsubscribe function. Reconnects send `Last-Event-ID` from the
+  last `id:` the client actually received. A **410** `LiveResumeGap` (**OKE1210**) means that cursor
+  is gone.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Subscribe to a shipment feed
+
+```typescript
+import { shipmentStatus } from "@/signals/orders";
+
+const stop = api.live(
+  shipmentStatus,
+  { orderId: "ord_9c2e" },
+  {
+    onEvent: (event) => {
+      // { orderId, status: "packed" | "shipped" | "delivered", eta? }
+      updateTrackingCard(event.status, event.eta);
+    },
+    onError: (err) => {
+      showTrackingBanner(err);
+    },
+    autoResubscribe: false, // default — true reopens after a drop (500ms…30s backoff)
+  },
+);
+```
+
+</Step>
+
+<Step>
+### Clean up when the shopper leaves the page
+
+```typescript
+stop(); // useEffect cleanup / process exit
+```
+
+`api.orders.events({ orderId }, { onEvent })` is the same shape on the exposing Flow.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Callback", "Flow-shaped", "autoResubscribe", "Live query"]}>
+
+<Tab value="Callback">
+
+```typescript
+const stop = api.live(
+  shipmentStatus,
+  { orderId: "ord_9c2e" },
+  {
+    onEvent: (event) => updateTrackingCard(event.status, event.eta),
+  },
+);
+stop();
+```
+
+</Tab>
+
+<Tab value="Flow-shaped">
+
+When the route is the exposing Flow itself:
+
+```typescript
+const stop = api.orders.events(
+  { orderId: "ord_9c2e" },
+  {
+    onEvent: (event) => {
+      updateTrackingCard(event.status, event.eta);
+    },
+  },
+);
+stop();
+```
+
+</Tab>
+
+<Tab value="autoResubscribe">
+
+```typescript
+const stop = api.live(
+  shipmentStatus,
+  { orderId: "ord_9c2e" },
+  {
+    onEvent: (event) => updateTrackingCard(event.status, event.eta),
+    onError: (err) => showTrackingBanner(err),
+    autoResubscribe: true, // reopen after a drop — 500ms…30s backoff
+  },
+);
+```
+
+Reconnects send `Last-Event-ID` from the last `id:` the client actually received.
+
+</Tab>
+
+<Tab value="Live query">
+
+When a resource opts into `live: true`, the compiler mounts `GET <path>/live` next to the CRUD
+verbs. That route streams **classified** row events — not a shared tape — so each subscriber only
+sees rows that still pass their RLS stamp + list filters (e.g. open tickets for this tenant).
+
+Prefer [React · useLiveQuery](/docs/client/react) for UI. Core transport helpers live on
+`okengine/client`.
+
+</Tab>
+
+</Tabs>
+
+## Live handlers
+
+| Option            | Type                 | Default | Meaning                                       |
+| ----------------- | -------------------- | ------- | --------------------------------------------- |
+| `onEvent`         | `(event) => void`    | —       | Required — each SSE payload                   |
+| `onError`         | `(err) => void`      | —       | 4xx, envelope, network drop                   |
+| `onOpen`          | `() => void`         | —       | Stream connected                              |
+| `autoResubscribe` | `boolean`            | `false` | Reopen after drop (500ms…30s backoff)         |
+| `via`             | `"unit.flow"` string | —       | Disambiguate when two exposures match equally |
+
+## Exposure matching
+
+The client picks the unique exposure whose `matchKey` fields are a subset of the input, preferring
+the largest match (`{ orderId }` beats firehose). A tie needs `via: "unit.flow"`.
+
+```typescript
+api.live(
+  shipmentStatus,
+  { orderId: "ord_9c2e" },
+  {
+    onEvent: updateTrackingCard,
+    via: "orders.events",
+  },
+);
+```
+
+Or call the exposing Flow directly: `api.orders.events(input, { onEvent })`.
+
+## Resume and LiveResumeGap
+
+Reconnects send `Last-Event-ID` from the last `id:` the client actually received.
+
+A **410** `LiveResumeGap` (**OKE1210**) means that cursor is gone — `onError` fires, the cursor is
+dropped, and `autoResubscribe` replays the remaining tape after backoff.
+
+Server exposure: [Signal · Live](/docs/elements/signal/live) and
+[HTTP · Live Streams](/docs/elements/flow/http#live-streams).
+
+## Live queries (`store.resource({ live: true })`)
+
+| `kind`    | Meaning                                                        |
+| --------- | -------------------------------------------------------------- |
+| `upsert`  | Row visible under stamp + query — merge/replace by primary key |
+| `revoked` | Row left visibility (`reason: "rls"` \| `"query"`) — remove    |
+| `delete`  | Row deleted in CDC — remove                                    |
+
+Every `mutate` from `useLiveQuery` generates a client UUID sent as the `X-Oke-Mutation-Id`
+header — the server echoes it onto that write's CDC events, so:
+
+- Your own late SSE echoes never double-apply (pending-set dedupe).
+- Reconnects replay-guard by event `seq` (`isReplayedEvent`).
+- Manual `refetch()` re-runs only the HTTP list read; reconnects always do a full
+  subscribe-protocol cycle (new snapshot + replay).
+
+| State            | Meaning                                                             |
+| ---------------- | ------------------------------------------------------------------- |
+| `isLoading`      | Waiting for the first snapshot — no data yet                        |
+| `isConnected`    | SSE stream is open                                                  |
+| `isReconnecting` | Stream dropped after a successful load; reconnect backoff in flight |
+
+**Consequence:** optimistic patches roll back automatically when the Flow returns `error !== null`.
+Server CDC / the successful response clear the override so the next upsert is authoritative.
+
+Full React wiring: [React](/docs/client/react).
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="api.live throws Multiple live exposures">
+  Two routes share the same match shape. Pass `via: "unit.flow"` or call the exposing flow
+  (`api.orders.events(input, {onEvent})`).
+</Accordion>
+
+<Accordion title="onError sees LiveResumeGap / HTTP 410">
+  The last `id:` is not on the server tape. The client drops the cursor. With `autoResubscribe:
+  true` the next request omits `Last-Event-ID` and replays what remains.
+</Accordion>
+
+<Accordion title="No events after subscribe">
+  Confirm the server exposed the signal (`.live(signal)` on GET or `http.live(signal)`), the
+  `matchKey` fields are present in `input`, and gates allow the identity. See [Signal ·
+  Live](/docs/elements/signal/live).
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [React](/docs/client/react) — `useLive`, `useLiveQuery`
+- [Calling](/docs/client/calling) — typed proxy and envelopes
+- [Signal · Live](/docs/elements/signal/live) — tape, resume, OKE1210
+- [HTTP · Live Streams](/docs/elements/flow/http#live-streams) — server exposure
+- [Store](/docs/elements/store) — `live: true` on resources
+
+## Next
+
+<Cards>
+  <Card title="React" description="useLive and useLiveQuery hooks." href="/docs/client/react" />
+  <Card
+    title="Signal · Live"
+    description="Server tape, Last-Event-ID, resume gaps."
+    href="/docs/elements/signal/live"
+  />
+  <Card title="Calling" description="createClient and REST vs RPC." href="/docs/client/calling" />
+</Cards>

package/site/content/docs/client/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Client",
+  "icon": "Cable",
+  "pages": ["index", "calling", "auth", "live", "react"]
+}

package/site/content/docs/client/react.mdx

@@ -0,0 +1,249 @@
+---
+title: "React"
+description: "useSession, Can, useLive, and useLiveQuery from okengine/client-react — React helpers over createClient."
+icon: "Atom"
+source: "docs/spec/unified-theory.md"
+---
+
+`okengine/client-react` is a separate package so core `okengine/client` stays under the size
+budget. Hooks wrap the same typed client: session status, live SSE, and live resource lists with
+optimistic `mutate`.
+
+For developers building React storefronts and ops consoles on top of `createClient`.
+
+<Callout title="The one rule">
+  Pass the same `api` you built with `createClient`. Hooks never open a second client factory — they
+  subscribe, call Flows, and clean up on unmount.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Create the client and session
+
+```typescript title="web/src/session.ts"
+import { createClient } from "okengine/client";
+import { vault } from "okengine/vault";
+import { app } from "../../src/app";
+
+export const api = createClient(app, vault.env("PUBLIC_API_URL") ?? "", {
+  auth: { mode: "cookie", csrfConfigured: true },
+});
+```
+
+</Step>
+
+<Step>
+### Show the signed-in shopper in the header
+
+```typescript title="web/src/AccountMenu.tsx"
+import { Can, useSession } from "okengine/client-react";
+import { api } from "./session";
+
+export function AccountMenu() {
+  const { status, user, signOut } = useSession(api.auth!);
+
+  if (status === "loading") return null;
+  if (status === "unauthenticated") return <a href="/sign-in">Sign in</a>;
+
+  return (
+    <>
+      <Can auth={api.auth!} all={["orders:write"]} fallback={null}>
+        <a href="/fulfillment">Fulfillment</a>
+      </Can>
+      <button type="button" onClick={() => signOut()}>
+        {user?.email}
+      </button>
+    </>
+  );
+}
+```
+
+`Can` / `useAuthorize` are UI-only — Gate on Flows remains real authz.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["useSession", "Can / useAuthorize", "useLive", "useLiveQuery", "mutate"]}>
+
+<Tab value="useSession">
+
+```typescript
+import { useSession } from "okengine/client-react";
+
+const { status, user, accessToken, refresh, signOut } = useSession(api.auth!);
+```
+
+| Field         | Meaning                                                 |
+| ------------- | ------------------------------------------------------- |
+| `status`      | `"loading"` \| `"authenticated"` \| `"unauthenticated"` |
+| `user`        | `auth.me` payload or `null`                             |
+| `accessToken` | Current Bearer from `memorySession` (or `null`)         |
+| `refresh()`   | Re-run `auth.me`                                        |
+| `signOut()`   | `session.clear()` + unauthenticated                     |
+
+</Tab>
+
+<Tab value="Can / useAuthorize">
+
+```tsx
+import { Can, useAuthorize } from "okengine/client-react";
+
+<Can auth={api.auth!} all={["orders:write"]} fallback={<Denied />}>
+  <FulfillmentLink />
+</Can>;
+
+const { status, missing } = useAuthorize(api.auth!, { all: ["orders:write"] });
+```
+
+UI chrome only — Gate on Flows is the security boundary. Prefer these over bare `useScope` /
+`useCan`.
+
+</Tab>
+
+<Tab value="useLive">
+
+```typescript
+import { useLive } from "okengine/client-react";
+import { shipmentStatus } from "@/signals/orders";
+
+const { events, latest, error, isConnected } = useLive(
+  api,
+  shipmentStatus,
+  { orderId: "ord_9c2e" },
+  {
+    autoResubscribe: true,
+  },
+);
+
+// latest?.status → "packed" | "shipped" | "delivered"
+```
+
+Cleanup calls `stop()` on unmount. Changing `signal` / `input` / `via` resets `events`.
+
+| Option            | Meaning                                |
+| ----------------- | -------------------------------------- |
+| `autoResubscribe` | Reopen after drop (same as `api.live`) |
+| `via`             | Disambiguate equal exposure matches    |
+
+</Tab>
+
+<Tab value="useLiveQuery">
+
+```typescript
+import { useLiveQuery } from "okengine/client-react";
+
+const { data, error, isLoading, isConnected, isReconnecting, refetch, mutate } = useLiveQuery({
+  api,
+  listFlow: api.inbox.list,
+  query: { status: "open", assignee: "me" },
+  live: { method: "GET", path: "/inbox/live" }, // from app.$routes
+  options: {
+    enabled: session.status === "authenticated", // default true — idle when false
+    refreshKey: workspaceId, // switch workspace → full re-subscribe
+    onAuthRefresh: onAuthRefreshed, // auth.refresh() → new snapshot + replay
+  },
+});
+```
+
+| State            | Meaning                                                             |
+| ---------------- | ------------------------------------------------------------------- |
+| `isLoading`      | Waiting for the first snapshot — no data yet                        |
+| `isConnected`    | SSE stream is open                                                  |
+| `isReconnecting` | Stream dropped after a successful load; reconnect backoff in flight |
+
+</Tab>
+
+<Tab value="mutate">
+
+```typescript
+await mutate(
+  api.inbox.update,
+  { id: ticketId, status: "resolved" },
+  {
+    optimistic: (rows) =>
+      rows.map((row) => (row.id === ticketId ? { ...row, status: "resolved" } : row)),
+    pkOf: (input) => input.id,
+  },
+);
+```
+
+Every `mutate` call generates a client UUID sent as the `X-Oke-Mutation-Id` header — the server
+echoes it onto that write's CDC events for pending-set dedupe and replay guards.
+
+**Consequence:** optimistic patches roll back automatically when the Flow returns `error !== null`.
+Server CDC / the successful response clear the override so the next upsert is authoritative.
+
+</Tab>
+
+</Tabs>
+
+## Package boundary
+
+| Export                                    | Package                 | Role                                        |
+| ----------------------------------------- | ----------------------- | ------------------------------------------- |
+| `createClient` / `api.live`               | `okengine/client`       | Typed proxy + SSE subscribe                 |
+| `createAuthClient` / `memorySession`      | `okengine/client/auth`  | Secure session orchestration                |
+| `vault` / `vault.env`                     | `okengine/vault`        | Env + config contracts (subpath — not root) |
+| `useSession` / `useLive` / `useLiveQuery` | `okengine/client-react` | React hooks (`react` optional peer)         |
+| `subscribeLiveResource`                   | `okengine/client-react` | Non-hook live resource stream helper        |
+
+Prefer [`createAuthClient`](/docs/client/auth) for cookie/Bearer sessions and method helpers.
+`useLiveQuery` accepts `listPath` to derive `GET ${listPath}/live` when `live` is omitted.
+
+## `useLiveQuery` options
+
+| Option          | Meaning                                        |
+| --------------- | ---------------------------------------------- |
+| `enabled`       | Default `true` — idle when `false`             |
+| `refreshKey`    | Identity change → full re-subscribe            |
+| `onAuthRefresh` | After `auth.refresh()` → new snapshot + replay |
+
+`refetch()` re-runs only the HTTP list read; reconnects always do a full subscribe-protocol cycle
+(new snapshot + replay). Event kinds and resume physics: [Live](/docs/client/live).
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Cannot find module okengine/client-react">
+  Install / import the React package separately. Core `okengine/client` does not re-export hooks —
+  that keeps the client runtime under budget.
+</Accordion>
+
+<Accordion title="useSession stuck on loading">
+  Confirm `auth.me` is adopted, Bearer `getToken` returns a token, and the me Flow is reachable.
+  Without a token, status becomes `"unauthenticated"`.
+</Accordion>
+
+<Accordion title="useLiveQuery never connects">
+  Pass `live: { method, path }` from `app.$routes` for the resource’s `/live` route. Set
+  `enabled: true` (or omit). See [Live](/docs/client/live) for exposure and resume errors.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Auth](/docs/client/auth) — `memorySession` and gate denials
+- [Live](/docs/client/live) — `api.live`, resume, live query kinds
+- [Calling](/docs/client/calling) — envelopes and list pager
+- [Signal · Live](/docs/elements/signal/live) — server tape
+- [Store](/docs/elements/store) — `live: true` resources
+
+## Next
+
+<Cards>
+  <Card
+    title="Live"
+    description="SSE subscribe and live resource physics."
+    href="/docs/client/live"
+  />
+  <Card title="Auth" description="Bearer sessions behind the hooks." href="/docs/client/auth" />
+  <Card title="Calling" description="createClient forms and options." href="/docs/client/calling" />
+</Cards>