@stapel/chat-react 0.1.0

package/nav-manifest.json

@@ -0,0 +1,25 @@
+{
+  "package": "@stapel/chat-react",
+  "version": "0.1.0",
+  "entries": [
+    {
+      "id": "chat.conversations",
+      "labelKey": "chat.nav.conversations",
+      "icon": "MessageOutlined",
+      "route": {
+        "path": "chat"
+      },
+      "component": {
+        "export": "ConversationListPanel",
+        "subpath": "default"
+      },
+      "placement": {
+        "level": "top"
+      },
+      "menuVisibleDefault": true,
+      "requiresAuth": true,
+      "surface": "member",
+      "order": 25
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@stapel/chat-react",
+  "version": "0.1.0",
+  "description": "Headless React pair for stapel-chat: typed API client, TanStack Query hooks, a seq-ordered thread store, and ONE transport seam behind which the module's own resumable WebSocket protocol (hello/welcome/replay/replay_done/message/error) and seq-anchored polling are interchangeable — the UI never knows which is live. Conversation list with unread badges, thread replay + live tail, REST send, direct-thread idempotency for \"message the seller\", monotonic read markers. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usestapel/stapel-react.git",
+    "directory": "packages/chat-react"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./default": {
+      "types": "./dist/default/index.d.ts",
+      "default": "./dist/default/index.js"
+    },
+    "./i18n/ru": {
+      "types": "./dist/i18n/ru.d.ts",
+      "default": "./dist/i18n/ru.js"
+    },
+    "./i18n/es": {
+      "types": "./dist/i18n/es.d.ts",
+      "default": "./dist/i18n/es.js"
+    },
+    "./manifest": "./manifest.json",
+    "./manifest.json": "./manifest.json",
+    "./nav-manifest": "./nav-manifest.json",
+    "./nav-manifest.json": "./nav-manifest.json",
+    "./llms.txt": "./llms.txt",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md",
+    "MODULE.md",
+    "CHANGELOG.md",
+    "manifest.json",
+    "nav-manifest.json",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.demo.json && vitest run --exclude test/prodBundlePurity.test.ts",
+    "test:pack": "vitest run test/prodBundlePurity.test.ts",
+    "lint": "eslint .",
+    "size": "size-limit"
+  },
+  "size-limit": [
+    {
+      "name": "index — headless pair (client + hooks + thread store + transport seam)",
+      "path": "dist/index.js",
+      "limit": "9 KB"
+    },
+    {
+      "name": "default — the antd chat skin must stay out of the main bundle",
+      "path": "dist/default/index.js",
+      "limit": "10 KB"
+    },
+    {
+      "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry",
+      "path": "dist/i18n/ru.js",
+      "limit": "4 KB"
+    },
+    {
+      "name": "i18n/es — the Spanish bundle is opt-in, not carried by the main entry",
+      "path": "dist/i18n/es.js",
+      "limit": "3.5 KB"
+    }
+  ],
+  "peerDependencies": {
+    "@stapel/core": ">=0.14.0 <1.0.0",
+    "@tanstack/react-query": "^5.0.0",
+    "antd": ">=5.20.0 <7",
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "antd": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@stapel/core": "workspace:^",
+    "@stapel/showcase": "workspace:^",
+    "@stapel/tokens": "workspace:^",
+    "@tanstack/react-query": "^5.81.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "antd": "^6.5.0",
+    "jsdom": "^26.1.0",
+    "msw": "^2.10.2",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "size-limit": "^11.2.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/analytics/generated/events.json

@@ -0,0 +1,7 @@
+{
+  "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
+  "package": "@stapel/chat-react",
+  "version": "0.1.0",
+  "defined": [],
+  "flows": []
+}

package/src/api/chatApi.ts

@@ -0,0 +1,142 @@
+import type { StapelClient, StapelRequestOptions } from "@stapel/core";
+import type {
+  ChatMessage,
+  Conversation,
+  ConversationKind,
+  ConversationListParams,
+  ConversationPage,
+  MessageHistoryParams,
+  MessagePage,
+  SendMessageRequest,
+} from "./types.js";
+
+/**
+ * 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: Record<string, string> = {
+  "X-Requested-With": "XMLHttpRequest",
+};
+
+function mutating(
+  options?: Omit<StapelRequestOptions, "method" | "body">
+): Omit<StapelRequestOptions, "method" | "body"> {
+  return {
+    ...options,
+    headers: { ...CSRF_HEADERS, ...options?.headers },
+  };
+}
+
+/** Anchor/direction/limit → a query object, omitting what was not asked for. */
+function pageQuery(
+  params: ConversationListParams | MessageHistoryParams | undefined
+): Record<string, string | number> {
+  const query: Record<string, string | number> = {};
+  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;
+}
+
+/**
+ * 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 function createChatApi(client: StapelClient): ChatApi {
+  const conversationPath = (id: string): string =>
+    `/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()
+      ),
+  };
+}

package/src/api/extensions.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 {};