@djangocfg/widget-assistant 0.3.11 → 0.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "A site assistant on top of @djangocfg/widget-chat: the SSE wire and session layer, a persistent host, docked column, floating button and sheet, dictation, Help and 17 built-in locales",
   "keywords": [
     "chat",
@@ -44,19 +44,19 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@djangocfg/widget-chat": "^0.1.27",
+    "@djangocfg/widget-chat": "^0.1.28",
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.626",
-    "@djangocfg/ui-core": "^2.1.626",
+    "@djangocfg/i18n": "^2.1.627",
+    "@djangocfg/ui-core": "^2.1.627",
     "lucide-react": "^1.68.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.626",
-    "@djangocfg/typescript-config": "^2.1.626",
-    "@djangocfg/ui-core": "^2.1.626",
+    "@djangocfg/i18n": "^2.1.627",
+    "@djangocfg/typescript-config": "^2.1.627",
+    "@djangocfg/ui-core": "^2.1.627",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/index.ts

@@ -11,6 +11,20 @@ export { AssistantHostProvider, AssistantPortal, AssistantSlot, AssistantHeaderA
 export { useSession, type Session, type SessionCopy, type SessionDeps, type SessionNotice, type ThreadState } from './stream/useSession';
 export { relativeTime, restoreSession, type SessionStorage, type ThreadApi } from './stream/sessions';
 export { SessionsMenu } from './sessions/SessionsMenu';
+export { createSessionStorage, useRememberedSession } from './sessions/storage';
+export {
+  createChatTransport,
+  storedMessageOf,
+  storedThreadOf,
+  type ChatCallResult,
+  type ChatConnection,
+  type ChatMessageShape,
+  type ChatThreadCalls,
+  type ChatThreadDetailShape,
+  type ChatThreadListItemShape,
+  type ChatThreadShape,
+  type ChatTransportConfig,
+} from './sessions/kit';
 export { createStreamAdapter, type AdapterDeps } from './stream/adapter';
 export { reconcile, type Reconciled } from './stream/reconcile';
 export { fromStored, fromStoredThread } from './stream/fromStored';

package/src/sessions/kit.ts

@@ -0,0 +1,119 @@
+import type { StoredConversation, StoredMessage, StoredStatus, StoredThread } from '../wire/stored';
+import { createTransport, ThreadNotFoundError, type ChatTransport, type SendInput, type TransportConfig } from '../wire/transport';
+import type { ThreadApi } from '../stream/sessions';
+
+/**
+ * The chat API kit's thread shapes (django-cfg `django_llm.agent.chat.api`), as the generated client names them (`ChatThread`, `ChatThreadListItem`,
+ * `ChatThreadDetail`, `ChatMessage`). Structural and read-only: a generated type is assignable (its enums are string enums), and a field the contract
+ * changes shows up at the host's call site as a type error. Only the fields the widget reads are listed.
+ */
+export interface ChatMessageShape {
+  id: string;
+  seq: number;
+  role: string;
+  text: string;
+  status: string;
+  /** `''` when there is none. */
+  error_code: string | null;
+  parts: ReadonlyArray<{ kind: string; data?: unknown }>;
+  created_at: string;
+}
+export interface ChatThreadShape {
+  id: string;
+  title: string;
+  updated_at: string;
+}
+export interface ChatThreadListItemShape extends ChatThreadShape {
+  message_count: number;
+  last_message_at: string | null;
+}
+export interface ChatThreadDetailShape extends ChatThreadShape {
+  messages: readonly ChatMessageShape[];
+}
+
+/** What a generated hey-api call resolves to (`{data, error, response}`); `response.status` carries a 404. */
+export interface ChatCallResult<T> {
+  data?: T;
+  error?: unknown;
+  response?: { status: number };
+}
+
+/** The three plain calls of the kit's thread routes, as the host maps them from its generated client (`Chat.chatThreadsList`, ...). The stream is not among them: no schema describes it. */
+export interface ChatThreadCalls {
+  list: (options: { signal?: AbortSignal }) => Promise<ChatCallResult<readonly ChatThreadListItemShape[]>>;
+  create: (options: { body?: { kind?: string } }) => Promise<ChatCallResult<ChatThreadShape>>;
+  retrieve: (options: { path: { thread_id: string }; signal?: AbortSignal }) => Promise<ChatCallResult<ChatThreadDetailShape>>;
+}
+
+const STATUSES: readonly StoredStatus[] = ['done', 'running', 'error', 'cancelled'];
+
+/** The kit's message as the widget's stored message. An unknown status reads as `error` (never a spinner without a stream). */
+export function storedMessageOf(message: ChatMessageShape): StoredMessage {
+  return {
+    id: message.id,
+    seq: message.seq,
+    role: message.role === 'user' ? 'user' : 'assistant',
+    text: message.text,
+    parts: message.parts.map((part) => ({ kind: part.kind, data: part.data })),
+    status: (STATUSES as readonly string[]).includes(message.status) ? (message.status as StoredStatus) : 'error',
+    error_code: message.error_code ? message.error_code : null,
+    created_at: message.created_at,
+  };
+}
+
+/** A listed row, or a freshly created thread (`POST` answers without the counters). */
+export function storedThreadOf(row: ChatThreadShape & Partial<Pick<ChatThreadListItemShape, 'message_count' | 'last_message_at'>>): StoredThread {
+  return { id: row.id, title: row.title, last_message_at: row.last_message_at ?? row.updated_at, message_count: row.message_count ?? 0 };
+}
+
+export interface ChatTransportConfig
+  extends Pick<TransportConfig, 'getToken' | 'headers' | 'idleMs' | 'streamFetch'> {
+  /** The thread calls of the generated client. */
+  client: ChatThreadCalls;
+  /** API origin, no trailing slash (the stream is called directly, never through a rewrite). */
+  baseUrl: string;
+  /** Where the kit is mounted, e.g. `/apix/assistant` (no trailing slash). The stream goes to `<mount>/threads/<id>/messages/`. */
+  mount: string;
+  /** `false` when the kit was mounted with `trailing_slash=False`. Default `true`. */
+  trailingSlash?: boolean;
+  /** The chat kind "New chat" asks for; omit where the server named a default kind. */
+  kind?: string;
+}
+
+export interface ChatConnection {
+  /** Hand to `useSession({ transport })`. */
+  transport: ChatTransport;
+  /** Hand to `useSession({ api })`. */
+  api: ThreadApi;
+}
+
+/**
+ * Everything a host connects to the kit, from the generated client's three thread calls: the SSE transport (`POST <mount>/threads/<id>/messages`, the frames of
+ * `wire-contract.md`) and the `ThreadApi` for list / new chat / load (a 404 is `ThreadNotFoundError`, an error body or an absent one is a plain `Error`).
+ * The host adds renderers, words, auth (`getToken` / `streamFetch`) and the mount point; nothing else.
+ */
+export function createChatTransport(config: ChatTransportConfig): ChatConnection {
+  const { client, baseUrl, mount, kind, trailingSlash = true } = config;
+  const tail = trailingSlash ? '/' : '';
+  const streamUrl = ({ threadId }: SendInput) => `${mount}/threads/${encodeURIComponent(threadId ?? '')}/messages${tail}`;
+  const transport = createTransport({ baseUrl, streamUrl, getToken: config.getToken, headers: config.headers, idleMs: config.idleMs, streamFetch: config.streamFetch });
+  const api: ThreadApi = {
+    async list(signal) {
+      const res = await client.list({ signal });
+      if (res.error || !res.data) throw new Error('chat threads');
+      return res.data.map(storedThreadOf);
+    },
+    async create() {
+      const res = await client.create(kind ? { body: { kind } } : {});
+      if (res.error || !res.data) throw new Error('chat create');
+      return storedThreadOf(res.data);
+    },
+    async load(id, signal): Promise<StoredConversation> {
+      const res = await client.retrieve({ path: { thread_id: id }, signal });
+      if (res.response?.status === 404) throw new ThreadNotFoundError();
+      if (res.error || !res.data) throw new Error('chat thread');
+      return { id: res.data.id, messages: res.data.messages.map(storedMessageOf) };
+    },
+  };
+  return { transport, api };
+}

package/src/sessions/storage.ts

@@ -0,0 +1,32 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import type { SessionStorage } from '../stream/sessions';
+
+/** The last used session id in a Storage (default `localStorage`). Never throws: remembering is a convenience (private mode, a full quota, SSR). */
+export function createSessionStorage(key: string, backing?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>): SessionStorage {
+  const store = () => backing ?? (typeof localStorage === 'undefined' ? null : localStorage);
+  return {
+    read: () => {
+      try {
+        return store()?.getItem(key) ?? null;
+      } catch {
+        return null;
+      }
+    },
+    write: (id) => {
+      try {
+        if (id) store()?.setItem(key, id);
+        else store()?.removeItem(key);
+      } catch {
+        // see above
+      }
+    },
+  };
+}
+
+/** A stable `SessionStorage` for `useSession({ storage })`: the key should be namespaced to the app (and to the account if accounts share a browser). */
+export function useRememberedSession(key: string): SessionStorage {
+  return useMemo(() => createSessionStorage(key), [key]);
+}