@stapel/chat-react 0.1.0

package/dist/realtime/frames.js

@@ -0,0 +1,123 @@
+/**
+ * The stapel-chat WebSocket protocol, typed.
+ *
+ * This is a MIRROR of the module's own contract, not an invention:
+ * `stapel_chat/consumers.py` (`ChatConsumer`) and `stapel_chat/realtime.py`
+ * (`message_frame`) are the source, and `MODULE.md` §"Realtime protocol"
+ * states it in one line:
+ *
+ * ```
+ * client → server:  hello{last_seq} / send{body,attachments,reply_to} / ack{seq} / ping
+ * server → client:  welcome{server_seq} / message{…seq} / replay_done{up_to_seq} / error{code,message} / pong
+ * ```
+ *
+ * The WS surface is invisible to `schema.json` (OpenAPI describes HTTP), so
+ * these types cannot be generated today — the realtime spec (§8) parks the
+ * frame contract in the `events.json` family for later. Until then this file
+ * is the pair's declared mirror and `test/frames.test.ts` pins it against the
+ * shapes the consumer actually sends.
+ *
+ * Nothing here imports React or `@stapel/core`: it is plain protocol, so the
+ * future `@stapel/realtime` substrate can subsume it without dragging the UI.
+ */
+/**
+ * Widest resume gap the server replays inline (`consumers.REPLAY_LIMIT`).
+ * Past it the server answers `error{resync}` instead, and the client
+ * re-hydrates from the REST history. Mirrored here so the client can SAY that
+ * before the server has to.
+ */
+export const CHAT_WS_REPLAY_LIMIT = 500;
+/** `ChatConsumer.connect()` closes with this when `scope["user"]` is unset. */
+export const CHAT_WS_CLOSE_UNAUTHENTICATED = 4401;
+/** …and with this when the caller is not a participant of the conversation. */
+export const CHAT_WS_CLOSE_NOT_PARTICIPANT = 4403;
+/** The one error code that means "stop replaying, re-read the journal". */
+export const CHAT_WS_RESYNC = "resync";
+// ── parsing (the wire is untrusted structured text) ──────────────────────────
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function str(value) {
+    return typeof value === "string" ? value : null;
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Narrow one decoded server frame, or `null` for anything this build does not
+ * understand (an unknown `type`, a missing field, a `seq` that is not a
+ * number). Unknown is DROPPED, never coerced: a frame this client cannot read
+ * must not advance the seq cursor, or the gap it leaves is invisible.
+ */
+export function parseServerFrame(value) {
+    if (!isRecord(value))
+        return null;
+    switch (value.type) {
+        case "welcome": {
+            const conversationId = str(value.conversation_id);
+            const serverSeq = num(value.server_seq);
+            if (conversationId === null || serverSeq === null)
+                return null;
+            return {
+                type: "welcome",
+                conversation_id: conversationId,
+                server_seq: serverSeq,
+            };
+        }
+        case "message": {
+            const seq = num(value.seq);
+            const messageId = str(value.message_id);
+            const conversationId = str(value.conversation_id);
+            const createdAt = str(value.created_at);
+            if (seq === null ||
+                messageId === null ||
+                conversationId === null ||
+                createdAt === null) {
+                return null;
+            }
+            const attachments = Array.isArray(value.attachments)
+                ? value.attachments.filter((a) => typeof a === "string")
+                : [];
+            return {
+                type: "message",
+                message_id: messageId,
+                conversation_id: conversationId,
+                sender_id: str(value.sender_id),
+                seq,
+                kind: str(value.kind) ?? "text",
+                body: str(value.body) ?? "",
+                reply_to: str(value.reply_to),
+                attachments,
+                created_at: createdAt,
+            };
+        }
+        case "replay_done": {
+            const upTo = num(value.up_to_seq);
+            if (upTo === null)
+                return null;
+            return { type: "replay_done", up_to_seq: upTo };
+        }
+        case "error": {
+            const code = str(value.code);
+            if (code === null)
+                return null;
+            return { type: "error", code, message: str(value.message) ?? "" };
+        }
+        case "pong":
+            return { type: "pong" };
+        default:
+            return null;
+    }
+}
+/** Decode a socket payload (JSON text) into a frame, or `null`. */
+export function decodeServerFrame(data) {
+    if (typeof data !== "string")
+        return null;
+    try {
+        return parseServerFrame(JSON.parse(data));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=frames.js.map

package/dist/realtime/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../src/realtime/frames.ts"],"names":[],"mappings":"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"}

package/dist/realtime/streams.d.ts

@@ -0,0 +1,49 @@
+/**
+ * How this pair NAMES the things it can be fresh about (realtime spec §7,
+ * "how a pair declares its channels"): typed stream keys plus the one rule
+ * that turns a key into a socket URL. Everything that decides *whether* a stream
+ * has a socket at all lives here, so the transport seam above can stay a
+ * two-line question.
+ */
+/** A conversation's own journal — the module mounts a socket per thread. */
+export interface ChatConversationStream {
+    readonly kind: "conversation";
+    readonly conversationId: string;
+}
+/**
+ * The caller's inbox (their conversation list).
+ *
+ * There is NO socket for this one, and that is a fact about the backend, not
+ * a gap in this pair: `stapel_chat.routing` mounts exactly one pattern,
+ * `ws/chat/<uuid:conversation_id>`, and the Channels group a message fans out
+ * to is `chat.conv.<id>` — per thread. Nothing broadcasts "your list moved".
+ * So the inbox is kept fresh by the polling half of the seam, and the seam is
+ * the reason no screen has to know that.
+ */
+export interface ChatInboxStream {
+    readonly kind: "inbox";
+}
+export type ChatStreamKey = ChatConversationStream | ChatInboxStream;
+export declare function chatConversationStream(conversationId: string): ChatConversationStream;
+export declare function chatInboxStream(): ChatInboxStream;
+/** A stable string for a stream key — a React dependency, a log line. */
+export declare function chatStreamId(stream: ChatStreamKey): string;
+/**
+ * Derive the socket base from the REST base URL.
+ *
+ * The mount point is canonical (`stapel_chat/routing.py`, and the fleet
+ * convention `/ws/<mod>/...` from the realtime spec §8): the sockets sit at
+ * the HOST ROOT, not under the module's API prefix, so only the origin of
+ * `baseUrl` is used. `http` → `ws`, `https` → `wss`.
+ *
+ * Returns `null` when no origin can be resolved — a relative `baseUrl` with
+ * no `origin` (server-side rendering, a node test). `null` is not a failure:
+ * it means "this build cannot open a socket", and the transport seam polls.
+ */
+export declare function deriveChatSocketBase(baseUrl: string, origin?: string | null): string | null;
+/**
+ * The socket URL for a stream, or `null` when the stream has none (the
+ * inbox) or no base could be derived.
+ */
+export declare function chatSocketUrl(base: string | null, stream: ChatStreamKey): string | null;
+//# sourceMappingURL=streams.d.ts.map

package/dist/realtime/streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../../src/realtime/streams.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,aAAa,GAAG,sBAAsB,GAAG,eAAe,CAAC;AAErE,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,MAAM,GACrB,sBAAsB,CAExB;AAED,wBAAgB,eAAe,IAAI,eAAe,CAEjD;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAI1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,GAAG,IAAI,CASf;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,MAAM,EAAE,aAAa,GACpB,MAAM,GAAG,IAAI,CAIf"}

package/dist/realtime/streams.js

@@ -0,0 +1,52 @@
+/**
+ * How this pair NAMES the things it can be fresh about (realtime spec §7,
+ * "how a pair declares its channels"): typed stream keys plus the one rule
+ * that turns a key into a socket URL. Everything that decides *whether* a stream
+ * has a socket at all lives here, so the transport seam above can stay a
+ * two-line question.
+ */
+export function chatConversationStream(conversationId) {
+    return { kind: "conversation", conversationId };
+}
+export function chatInboxStream() {
+    return { kind: "inbox" };
+}
+/** A stable string for a stream key — a React dependency, a log line. */
+export function chatStreamId(stream) {
+    return stream.kind === "conversation"
+        ? `conversation:${stream.conversationId}`
+        : "inbox";
+}
+/**
+ * Derive the socket base from the REST base URL.
+ *
+ * The mount point is canonical (`stapel_chat/routing.py`, and the fleet
+ * convention `/ws/<mod>/...` from the realtime spec §8): the sockets sit at
+ * the HOST ROOT, not under the module's API prefix, so only the origin of
+ * `baseUrl` is used. `http` → `ws`, `https` → `wss`.
+ *
+ * Returns `null` when no origin can be resolved — a relative `baseUrl` with
+ * no `origin` (server-side rendering, a node test). `null` is not a failure:
+ * it means "this build cannot open a socket", and the transport seam polls.
+ */
+export function deriveChatSocketBase(baseUrl, origin) {
+    try {
+        const url = new URL(baseUrl, origin ?? undefined);
+        const protocol = url.protocol === "https:" || url.protocol === "wss:" ? "wss:" : "ws:";
+        return `${protocol}//${url.host}/ws/chat/`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The socket URL for a stream, or `null` when the stream has none (the
+ * inbox) or no base could be derived.
+ */
+export function chatSocketUrl(base, stream) {
+    if (base === null || stream.kind !== "conversation")
+        return null;
+    const prefix = base.endsWith("/") ? base : `${base}/`;
+    return `${prefix}${encodeURIComponent(stream.conversationId)}`;
+}
+//# sourceMappingURL=streams.js.map

package/dist/realtime/streams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.js","sourceRoot":"","sources":["../../src/realtime/streams.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwBH,MAAM,UAAU,sBAAsB,CACpC,cAAsB;IAEtB,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,OAAO,MAAM,CAAC,IAAI,KAAK,cAAc;QACnC,CAAC,CAAC,gBAAgB,MAAM,CAAC,cAAc,EAAE;QACzC,CAAC,CAAC,OAAO,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,MAAsB;IAEtB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,SAAS,CAAC,CAAC;QAClD,MAAM,QAAQ,GACZ,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;QACxE,OAAO,GAAG,QAAQ,KAAK,GAAG,CAAC,IAAI,WAAW,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAmB,EACnB,MAAqB;IAErB,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC;IACtD,OAAO,GAAG,MAAM,GAAG,kBAAkB,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;AACjE,CAAC"}

package/llms.txt

@@ -0,0 +1,89 @@
+# @stapel/chat-react 0.1.0
+
+Headless React flow pair for stapel-chat (contract >=0.2 <0.3) — business + state, zero visual opinion.
+Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
+verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
+
+## The one right way (do this, the rest is a review/lint smell)
+- No raw fetch/axios. The client is injected via <ChatProvider>/StapelConfigProvider;
+  every hook and flow already carries auth, refresh, and the error envelope.
+- Render errors, never try/catch them: a flow's state carries FlowError{code,params};
+  render `t(code, params)` and branch on `explainChatError(code)` remediation.
+- Server state = the use* hooks (query layer); keys come only from chatQueryKeys.
+- User strings = i18n keys (registerChatI18n); never string literals.
+- Sign-in UI = a headless flow component; copy it (shadcn-style) to restyle.
+
+## Layers
+api (typed client) · model (hooks, session) · flows (machines) · headless · i18n
+
+## Documented flows (flows.json — canonical id, steps, endpoints)
+
+## Operations (typed; use the named op, never a path string)
+Request/response schema names are in manifest.json + the generated types.
+Paths are relative to `/chat/api/v1/`.
+- chat_api_v1_conversations_create: POST /conversations
+- chat_api_v1_conversations_list: GET /conversations
+- chat_api_v1_conversations_messages_create: POST /conversations/{conversation_id}/messages
+- chat_api_v1_conversations_messages_list: GET /conversations/{conversation_id}/messages
+- chat_api_v1_conversations_read_create: POST /conversations/{conversation_id}/read
+- chat_api_v1_conversations_retrieve: GET /conversations/{conversation_id}
+- chat_api_v1_support_conversations_assign_create: POST /support/conversations/{conversation_id}/assign
+- chat_api_v1_support_conversations_reopen_create: POST /support/conversations/{conversation_id}/reopen
+- chat_api_v1_support_conversations_resolve_create: POST /support/conversations/{conversation_id}/resolve
+- chat_api_v1_support_queue_list: GET /support/queue
+
+## Query hooks (server state; keys come only from the key factory)
+- useConversation (query) → conversation
+- useLoadOlderMessages (mutation) → messages
+- useMarkRead (mutation) → markRead
+- useSendMessage (mutation) → sendMessage
+- useStartDirectChat (mutation) → createConversation
+- useThread (query) → messages
+
+## Errors (render t(code, params); UX from remediation)
+54 keys (full catalog: manifest.json §errors). By remediation: fix_input 25 · retry 16 · verify 5 · wait_and_retry 5 · contact_support 2 · reauthenticate 1.
+Param-bearing keys (interpolation slots matter):
+- error.400.field.blank [400] → fix_input {field}
+- error.400.field.does_not_exist [400] → fix_input {field}
+- error.400.field.invalid [400] → fix_input {field}
+- error.400.field.invalid_choice [400] → fix_input {field}
+- error.400.field.max_length [400] → fix_input {field,max_length}
+- error.400.field.max_value [400] → fix_input {field,max_value}
+- error.400.field.min_length [400] → fix_input {field,min_length}
+- error.400.field.min_value [400] → fix_input {field,min_value}
+- error.400.field.null [400] → fix_input {field}
+- error.400.field.required [400] → fix_input {field}
+- error.400.field.unique [400] → fix_input {field}
+- error.429.rate_limit [429] → wait_and_retry {retry_after_minutes}
+
+## Analytics events (typed; defineEvent → events.json, drift-gated)
+- (no app defineEvent() in this pair — its analytic events are the
+  auto-instrumented flow funnels below)
+
+## Flow funnels (auto-instrumented: flow.<id>.<step> {phase})
+
+```tsx
+// Typed event + tracked() click (the one right way; §3.1).
+const planSelected = defineEvent({
+  name: "pricing.plan.selected",
+  description: "User picked a plan",
+  props: { plan: prop.oneOf(["free", "pro", "team"], "Plan code") },
+});
+const { tracked } = useTracked();
+<Button onClick={tracked(planSelected, { plan }, startCheckout)} />
+// A click that STEPS a flow machine is already instrumented — mark it
+// data-analytics="flow" instead; tracked() on top double-counts (§3.2).
+```
+
+## Demos (defineDemo → manifest.demos; compiled, linted, rendered examples)
+- chat.conversations → <ConversationList> [default]  demo/ConversationList.demo.tsx
+- chat.start → <StartDirectChat> [default|no-seller|own-listing]  demo/StartDirectChat.demo.tsx
+- chat.thread → <ConversationThread> [default]  demo/ConversationThread.demo.tsx
+Each source file is the canonical usage snippet (open the default variant).
+
+## Snippets
+```tsx
+// Error rendering + remediation branch (one pattern for every pair).
+const r = explainChatError(err.code); // 'wait_and_retry' | 'verify' | ...
+return <Alert action={r}>{t(err.code, err.params)}</Alert>;
+```