@stapel/chat-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @stapel/chat-react

package/MODULE.md

@@ -0,0 +1,118 @@
+# @stapel/chat-react — module guide
+
+Headless React pair for **stapel-chat**. This is the human companion to the
+generated `llms.txt` (agent context) and `manifest.json` (machine catalog).
+
+## The one thing to understand first: the transport seam
+
+stapel-chat can deliver the same journal two ways — the REST history, and its
+own resumable WebSocket protocol (`ws/chat/<uuid:conversation_id>`, exported by
+`stapel_chat.routing` since 0.2.2). This pair wires **both**, behind one hook,
+and no component above that hook can tell which is running:
+
+```
+useChatFreshness(streamKey, mapToQueryKeys, { fallbackRefetchInterval })
+    ├── socket  → hello{last_seq} → welcome → replay… → replay_done → live
+    │              frames, seq-deduped; error{resync} → re-hydrate
+    └── polling → a visibility-aware tick, exponential backoff on failures
+```
+
+Both ends do the same thing with what they learn: **refetch the thread query**,
+whose query function advances the window BY SEQ
+(`GET …/messages?direction=prev&anchor=<tip>`). A socket frame does not carry
+its payload into the cache — it says "there is something after your tip" and
+the store goes and gets it. That is why the screens, and their tests, are
+written once.
+
+Writes never go over the socket. The `send` frame is typed (a mirror must be
+complete) and never emitted: its refusals carry socket-local codes
+(`empty`, `too_long`, …) that are not in the module's error registry, so they
+have no i18n key and no remediation. `POST …/messages` answers with the
+persisted row and a real error envelope.
+
+**When `@stapel/realtime` phase 1 lands**, `src/flows/freshness.ts` is the whole
+migration: `createChatSocket` goes away, `useSignalInvalidate` takes its place,
+and this pair's tests must stay green with no edits. Nothing above that file
+imports `realtime/`, so the blast radius is checkable rather than promised.
+
+## Layers
+
+- **api/** — `createChatApi(client)`; types alias the generated
+  `components["schemas"]` from stapel-chat's own `docs/schema.json` (never
+  parallel hand-written bodies). The support-operator half of the module
+  (`/support/queue`, assign / resolve / reopen) is deliberately absent — it is
+  an operator console, not the buyer-and-seller surface. `api/extensions.ts`
+  records the one request field that is NOT exposed and why.
+- **realtime/** — the protocol, typed (`frames.ts`), the resumable client
+  (`chatSocket.ts`), and the stream keys plus the URL rule (`streams.ts`). No
+  React, no `@stapel/core`: plain protocol the substrate can subsume.
+- **model/** — `chatQueryKeys` (one factory, `["chat"]` namespace),
+  `createChatRuntime` (which also resolves WHERE the socket is),
+  `threadWindow.ts` (the merge rules — the store's real logic, pure and
+  directly testable), `readMarker.ts`, queries and mutations.
+- **flows/** — the transport seam (`freshness.ts`) and the error fold. The flow
+  REGISTRY is a zero-flow shim: stapel-chat annotates no `@flow_step`, and its
+  multi-step-ness lives in the transport, not in a server-declared funnel.
+- **headless/** — render-prop components: `<ConversationList>`,
+  `<ConversationThread>`, `<MessageComposer>`, `<StartDirectChat>`, plus
+  `<ChatProvider>`. shadcn-copyable (frontend-standard §7).
+- **default/** — the opt-in antd skin (`@stapel/chat-react/default`).
+- **i18n/** — `CHAT_I18N_KEYS` + en bundle; the generated backend error bundle
+  is merged in so every `error.*` code has a fallback. See "Localization" below
+  for the one thing that is unusual here.
+- **nav/** — one MEMBER entry (`chat.conversations`). The thread route is not a
+  menu destination and is mounted by the container under its own `:id` child.
+
+## The thread store, in three rules
+
+1. **`seq` is the order.** Gapless and total; ordering by `created_at` is an
+   upstream anti-pattern. Every merge sorts, dedupes and detects holes by seq.
+2. **A window is contiguous or it is rebuilt.** A tail page that does not touch
+   the tip (or that the paginator flags as truncated with `has_prev`) is a
+   hole; the window is re-read from the newest page rather than stitched. That
+   is the REST twin of the socket's `error{resync}`.
+3. **The same row can arrive twice** — the sender's own REST answer and the
+   socket's fan-out of it. `mergeMessage` drops a seq the window already holds,
+   which is what makes both paths idempotent.
+
+## Localization — the twelve keys this pair owns
+
+stapel-chat ships **English only**: it has no `translations/` directory, so its
+12 error keys cannot appear in any locale catalogue upstream. `gen:errors` runs
+for this pair with `ERRORS_LOCALE_EXEMPT_OWNERS=stapel_chat` and
+`ERRORS_CATALOG_DIR` pointed at stapel-core's catalogue: the 42 cross-cutting
+keys come from core in ru/es (typed `Partial`, so the gap is visible to
+TypeScript), and the pair authors the 12 chat-owned texts in
+`src/i18n/{ru,es}.ts` beside its UI copy. `test/i18n.test.ts` proves every
+registry code resolves to a sentence in all three locales. When upstream ships
+`translations/errors.{ru,es}.json`, those twelve lines are deleted and the
+generated bundle covers them — the keys and the texts do not move.
+
+Unlike notifications-react, the `es` subpath here carries hand-written UI copy
+too: a marketplace's buyer-to-seller chat is the surface where a half-translated
+screen shows most.
+
+## Extension seams (frontend-standard §7)
+
+- The client is injected via `<ChatProvider>` / core's `StapelConfigProvider`
+  (per-module override) — pairs never hard-import a client.
+- The socket transport is injected: `createChatRuntime({ realtime: { webSocket } })`
+  takes any factory with `send`/`close` plus four callbacks, which is how the
+  tests drive the protocol frame by frame without a network.
+- `realtime.socketUrl: null` turns the socket half off for a deployment that has
+  no sockets (WSGI, no channel layer). Everything keeps working on the timer.
+- The headless layer is fully replaceable (copy-and-own); the antd skin is a
+  separate entry point nobody has to import.
+
+## Not in this version
+
+- **Attachments.** `SendMessageRequest.attachments` exists on the wire; wiring
+  it means wiring CDN upload rights into chat, and a control that is visible
+  but does nothing is worse than one that is absent.
+- **The support console.** `/support/queue`, assign / resolve / reopen — an
+  operator surface, not this one.
+- **A thread scoped to a listing.** `CreateConversationRequest.scope_key` is
+  ignored by the server (it resolves the scope itself), and a direct thread is
+  keyed by the participant PAIR — so buyer↔seller is one conversation across
+  every listing. A host that wants the listing named says so in the first
+  message.

package/README.md

@@ -0,0 +1,126 @@
+# @stapel/chat-react
+
+Headless React pair for **stapel-chat** (frontend-standard §2). Business +
+state only in the main entry, zero visual opinion — any design layers on top.
+Built on `@stapel/core` (typed client + `StapelApiError` envelope, token
+refresh, verification-403 interception, i18n engine, analytics seam, TanStack
+Query).
+
+Its backend delivers the same journal two ways — the REST history and its own
+resumable WebSocket protocol — and this pair wires **both, behind one seam**, so
+a deployment with sockets and one without run the same screens. See `MODULE.md`
+for the layer map and the seam's replacement criterion.
+
+## Install
+
+```
+pnpm add @stapel/chat-react @stapel/core @tanstack/react-query react
+```
+
+## Wire the app once
+
+```tsx
+import { createI18n, StapelProvider } from "@stapel/core";
+import { ChatProvider, createChatRuntime, registerChatI18n } from "@stapel/chat-react";
+
+const runtime = createChatRuntime({
+  baseUrl: "/chat/api/v1",
+  // Sockets are derived from baseUrl's origin (`/ws/chat/`, the module's
+  // canonical mount). On a deployment that has none, say so — it goes
+  // straight to polling instead of failing a handshake six times first:
+  //   realtime: { socketUrl: null },
+});
+const i18n = createI18n({ locale: "en" });
+registerChatI18n(i18n);
+
+export function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <StapelProvider client={runtime.client} i18n={i18n} cacheVersion="0.1.0">
+      <ChatProvider runtime={runtime}>{children}</ChatProvider>
+    </StapelProvider>
+  );
+}
+```
+
+## The inbox
+
+```tsx
+import { ConversationList } from "@stapel/chat-react";
+import { matchList } from "@stapel/core";
+
+<ConversationList>
+  {({ state }) =>
+    matchList(state, {
+      loading: () => <Spinner />,
+      failed: (error) => <ErrorPanel error={error} />,
+      empty: () => <p>{t("chat.list.empty")}</p>,
+      ready: (rows) => <List rows={rows} />, // rows carry `unread_count`
+    })
+  }
+</ConversationList>;
+```
+
+## A thread
+
+```tsx
+import { ConversationThread, MessageComposer } from "@stapel/chat-react";
+
+<ConversationThread conversationId={id}>
+  {({ state, hasOlder, loadOlder, transport }) => (
+    /* `transport` is "socket" | "polling" | "idle" — a LABEL. Nothing about
+       the thread's behaviour depends on it; that is the seam's whole point. */
+    ...
+  )}
+</ConversationThread>;
+
+<MessageComposer conversationId={id}>
+  {({ value, setValue, availability, send }) => (
+    /* `availability` is blocked-with-a-reason or available — a disabled
+       control here always has a sentence to show. */
+    ...
+  )}
+</MessageComposer>;
+```
+
+The thread replays, then stays live; the read marker advances to the tip while
+it is mounted and never moves backwards. Sending is REST — the persisted row
+comes back with its `seq` and is folded into the window.
+
+## "Message the seller"
+
+```tsx
+import { StartDirectChat } from "@stapel/chat-react";
+
+<StartDirectChat sellerId={listing.seller_id} viewerId={me?.id} onOpened={(c) => navigate(`/account/chat/${c.id}`)}>
+  {({ availability, start }) => ...}
+</StartDirectChat>;
+```
+
+Get-or-create: a direct thread is keyed by the participant pair under a unique
+constraint, so pressing twice — or writing to the same seller about a second
+listing — lands in the same conversation.
+
+## The antd skin (opt-in)
+
+```tsx
+import {
+  ConversationListPanel,
+  ConversationThreadPanel,
+  StartChatButton,
+} from "@stapel/chat-react/default";
+```
+
+Importing the subpath is the opt-in; consumers who bring their own visuals
+never pull `antd` into their bundle.
+
+## Locales
+
+```tsx
+import { registerChatI18nRu } from "@stapel/chat-react/i18n/ru";
+import { registerChatI18nEs } from "@stapel/chat-react/i18n/es";
+```
+
+Opt-in subpaths, so a host that ships one language carries one language. Both
+locales are complete over the pair's UI copy and over every backend error code
+the module can raise — including the twelve stapel-chat owns and does not
+localize upstream (see `MODULE.md`).

package/dist/api/chatApi.d.ts

@@ -0,0 +1,49 @@
+import type { StapelClient } from "@stapel/core";
+import type { ChatMessage, Conversation, ConversationKind, ConversationListParams, ConversationPage, MessageHistoryParams, MessagePage, SendMessageRequest } from "./types.js";
+/**
+ * The pair's typed operation surface — one method per stapel-chat endpoint a
+ * buyer/seller client may call, bound to the injected {@link StapelClient}
+ * (the per-module override seam of frontend-standard §7.2). Paths are relative
+ * to the runtime's `baseUrl` (`/chat/api/v1`).
+ *
+ * **WRITES NEVER GO OVER THE SOCKET.** stapel-chat's `ChatConsumer` accepts a
+ * `send` frame, and this pair deliberately does not use it: a message is a
+ * durable row with a locked `seq` allocation, and the REST path is the one
+ * that answers with the persisted row (and with a real error envelope when it
+ * refuses). The socket is a delivery convenience over that journal — see
+ * `src/realtime/`.
+ *
+ * The support-operator half of the module (`/support/queue`, assign / resolve
+ * / reopen) is intentionally absent: it is an operator console, not the
+ * buyer-and-seller surface this pair ships (spec §4.5 "Not in MVP").
+ *
+ * These operations will be GENERATED from schema.json operationIds by gen-api
+ * v2; until then they are hand-authored here (the ONE legal home of path
+ * strings — `stapel/no-string-paths` §2.3 carve-out).
+ */
+export interface ChatApi {
+    readonly client: StapelClient;
+    /** A page of the caller's conversations, newest activity first. */
+    conversations(params?: ConversationListParams): Promise<ConversationPage>;
+    /** One conversation (participant-only; 403 otherwise). */
+    conversation(conversationId: string): Promise<Conversation>;
+    /**
+     * Get-or-create a conversation. For `direct`, `participantIds` must name
+     * exactly one OTHER user: the thread is keyed by the (order-independent)
+     * participant pair, so a second call returns the same row — the idempotency
+     * "message the seller" is built on.
+     */
+    createConversation(kind: ConversationKind, participantIds?: readonly string[]): Promise<Conversation>;
+    /** A page of message history, anchored on `seq` (see {@link MessageHistoryParams}). */
+    messages(conversationId: string, params?: MessageHistoryParams): Promise<MessagePage>;
+    /** Append a message. Resolves with the persisted row, carrying its `seq`. */
+    sendMessage(conversationId: string, body: SendMessageRequest): Promise<ChatMessage>;
+    /**
+     * Advance the caller's read marker. The server never moves it backwards
+     * (`services.mark_read`), and neither does this pair — see
+     * `model/readMarker.ts`.
+     */
+    markRead(conversationId: string, uptoSeq: number): Promise<void>;
+}
+export declare function createChatApi(client: StapelClient): ChatApi;
+//# sourceMappingURL=chatApi.d.ts.map

package/dist/api/chatApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatApi.d.ts","sourceRoot":"","sources":["../../src/api/chatApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAwB,MAAM,cAAc,CAAC;AACvE,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAgCpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B,mEAAmE;IACnE,aAAa,CAAC,MAAM,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1E,0DAA0D;IAC1D,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5D;;;;;OAKG;IACH,kBAAkB,CAChB,IAAI,EAAE,gBAAgB,EACtB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GACjC,OAAO,CAAC,YAAY,CAAC,CAAC;IACzB,uFAAuF;IACvF,QAAQ,CACN,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,6EAA6E;IAC7E,WAAW,CACT,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CA2C3D"}

package/dist/api/chatApi.js

@@ -0,0 +1,46 @@
+/**
+ * CSRF rule for cookie-authenticated browser clients (mirrors auth-react): the
+ * simplest SPA rule is to always send `X-Requested-With: XMLHttpRequest` on
+ * mutating requests. Header-token clients ignore it; it is harmless there, so
+ * every mutation carries it.
+ */
+const CSRF_HEADERS = {
+    "X-Requested-With": "XMLHttpRequest",
+};
+function mutating(options) {
+    return {
+        ...options,
+        headers: { ...CSRF_HEADERS, ...options?.headers },
+    };
+}
+/** Anchor/direction/limit → a query object, omitting what was not asked for. */
+function pageQuery(params) {
+    const query = {};
+    if (params?.anchor !== undefined)
+        query.anchor = params.anchor;
+    if (params?.direction !== undefined)
+        query.direction = params.direction;
+    if (params?.limit !== undefined)
+        query.limit = params.limit;
+    return query;
+}
+export function createChatApi(client) {
+    const conversationPath = (id) => `/conversations/${encodeURIComponent(id)}`;
+    return {
+        client,
+        conversations: (params) => client.get("/conversations", { query: pageQuery(params) }),
+        conversation: (conversationId) => client.get(conversationPath(conversationId)),
+        createConversation: (kind, participantIds) => client.post("/conversations", {
+            kind,
+            ...(participantIds !== undefined
+                ? { participant_ids: [...participantIds] }
+                : {}),
+        }, mutating()),
+        messages: (conversationId, params) => client.get(`${conversationPath(conversationId)}/messages`, {
+            query: pageQuery(params),
+        }),
+        sendMessage: (conversationId, body) => client.post(`${conversationPath(conversationId)}/messages`, body, mutating()),
+        markRead: (conversationId, uptoSeq) => client.post(`${conversationPath(conversationId)}/read`, { upto_seq: uptoSeq }, mutating()),
+    };
+}
+//# sourceMappingURL=chatApi.js.map

package/dist/api/chatApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatApi.js","sourceRoot":"","sources":["../../src/api/chatApi.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,MAAM,YAAY,GAA2B;IAC3C,kBAAkB,EAAE,gBAAgB;CACrC,CAAC;AAEF,SAAS,QAAQ,CACf,OAAuD;IAEvD,OAAO;QACL,GAAG,OAAO;QACV,OAAO,EAAE,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;KAClD,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,SAAS,SAAS,CAChB,MAAiE;IAEjE,MAAM,KAAK,GAAoC,EAAE,CAAC;IAClD,IAAI,MAAM,EAAE,MAAM,KAAK,SAAS;QAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/D,IAAI,MAAM,EAAE,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACxE,IAAI,MAAM,EAAE,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC5D,OAAO,KAAK,CAAC;AACf,CAAC;AA0DD,MAAM,UAAU,aAAa,CAAC,MAAoB;IAChD,MAAM,gBAAgB,GAAG,CAAC,EAAU,EAAU,EAAE,CAC9C,kBAAkB,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC;IAE7C,OAAO;QACL,MAAM;QAEN,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CACxB,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QAE5D,YAAY,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC;QAE9E,kBAAkB,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,CAC3C,MAAM,CAAC,IAAI,CACT,gBAAgB,EAChB;YACE,IAAI;YACJ,GAAG,CAAC,cAAc,KAAK,SAAS;gBAC9B,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,GAAG,cAAc,CAAC,EAAE;gBAC1C,CAAC,CAAC,EAAE,CAAC;SACR,EACD,QAAQ,EAAE,CACX;QAEH,QAAQ,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,CACnC,MAAM,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAAC,cAAc,CAAC,WAAW,EAAE;YACzD,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC;SACzB,CAAC;QAEJ,WAAW,EAAE,CAAC,cAAc,EAAE,IAAI,EAAE,EAAE,CACpC,MAAM,CAAC,IAAI,CACT,GAAG,gBAAgB,CAAC,cAAc,CAAC,WAAW,EAC9C,IAAI,EACJ,QAAQ,EAAE,CACX;QAEH,QAAQ,EAAE,CAAC,cAAc,EAAE,OAAO,EAAE,EAAE,CACpC,MAAM,CAAC,IAAI,CACT,GAAG,gBAAgB,CAAC,cAAc,CAAC,OAAO,EAC1C,EAAE,QAAQ,EAAE,OAAO,EAAE,EACrB,QAAQ,EAAE,CACX;KACJ,CAAC;AACJ,CAAC"}

package/dist/api/extensions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hand-authored API surface the codegen does not (yet) cover. Everything that
+ * CAN be derived from schema.json belongs in the generated operations
+ * (`api/chatApi.ts`), not here.
+ *
+ * ── One field the operation surface deliberately does NOT expose ────────────
+ *
+ * `CreateConversationRequest.scope_key` exists in the schema and its own
+ * description says the rest: *"Ignored — the scope is resolved server-side
+ * from the request"* (`views.ConversationListCreateView.post` calls
+ * `get_scope_provider().resolve(request)` and never reads the field). A client
+ * that sends a listing id there would believe it had scoped the thread to a
+ * listing; the server would key the direct thread by the participant PAIR, as
+ * it always does. Rather than ship a parameter that silently does nothing,
+ * `createConversation` has no `scopeKey` argument at all — the listing context
+ * belongs in the first MESSAGE, which is durable, visible, and actually read.
+ */
+export {};
+//# sourceMappingURL=extensions.d.ts.map

package/dist/api/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/api/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC"}

package/dist/api/extensions.js

@@ -0,0 +1,19 @@
+/**
+ * Hand-authored API surface the codegen does not (yet) cover. Everything that
+ * CAN be derived from schema.json belongs in the generated operations
+ * (`api/chatApi.ts`), not here.
+ *
+ * ── One field the operation surface deliberately does NOT expose ────────────
+ *
+ * `CreateConversationRequest.scope_key` exists in the schema and its own
+ * description says the rest: *"Ignored — the scope is resolved server-side
+ * from the request"* (`views.ConversationListCreateView.post` calls
+ * `get_scope_provider().resolve(request)` and never reads the field). A client
+ * that sends a listing id there would believe it had scoped the thread to a
+ * listing; the server would key the direct thread by the participant PAIR, as
+ * it always does. Rather than ship a parameter that silently does nothing,
+ * `createConversation` has no `scopeKey` argument at all — the listing context
+ * belongs in the first MESSAGE, which is durable, visible, and actually read.
+ */
+export {};
+//# sourceMappingURL=extensions.js.map

package/dist/api/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../src/api/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC"}