@data-club/ai-hub 0.0.1

package/src/client/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Public re-exports for the `client/` directory.
+ *
+ * @see SPECIFICATIONS.md §7.8 — client SDK
+ */
+
+export { AIHubClient, AIHubRequestError } from "./AIHubClient.js";
+export type {
+  AIHubClientOptions,
+  LoginResponse,
+  ListSessionsOptions,
+  CreateSessionOptions,
+  PatchSessionOptions,
+  PatchSessionReasoningOptions,
+  AIHubEffort,
+  StreamChatBody,
+  StreamChatOptions,
+  AgentSummary,
+  CancelTurnResponse,
+  AdminUserView,
+  CreateUserBody,
+  AdminUserPasswordReveal,
+  CreateUserResponse,
+} from "./AIHubClient.js";
+export {
+  createMemoryTokenStorage,
+  resolveTokenStorage,
+} from "./tokenStorage.js";
+export type { TokenStorage, TokenStorageMode } from "./tokenStorage.js";
+export { parseSseStream } from "./sseParser.js";

package/src/client/sseParser.ts

@@ -0,0 +1,168 @@
+/**
+ * SSE → `AIHubEvent` parser.
+ *
+ * The ai-hub server emits each event as:
+ *
+ * ```
+ * event: <event-name>
+ * data: <json-payload>
+ *
+ * ```
+ *
+ * where `<json-payload>` is `{ seq, data?, state }` (see
+ * `packages/ai-hub-server/src/handlers/sse.ts`). The library does not use
+ * the browser's `EventSource` API (§9.5 — it can't carry custom auth
+ * headers); instead the SDK consumes the response body via
+ * `fetch` + `ReadableStream` and runs it through this parser.
+ *
+ * Heartbeat lines (`:hb\n\n`) are SSE comments and are skipped entirely —
+ * they reach the parser as a block whose only line starts with `:` and
+ * produce no event.
+ *
+ * @see SPECIFICATIONS.md §9.5 — why SSE (not EventSource)
+ */
+
+import type { AIHubEvent } from "../types.js";
+
+/**
+ * Parses a streaming `ReadableStream<Uint8Array>` of SSE bytes into an
+ * `AsyncIterable<AIHubEvent>`.
+ *
+ * The async generator stops when the underlying stream ends or when the
+ * stream's reader is released (e.g. on `AbortSignal` abort upstream).
+ * Malformed event blocks (no `event:` line, or `data:` JSON that doesn't
+ * parse) are skipped silently — the contract is "yield every valid event,"
+ * not "throw on the first garbage chunk." Real network corruption surfaces
+ * as a `stream_end` from the server (or a transport-level error from
+ * fetch, which the caller catches separately).
+ *
+ * @param body - the response body to parse.
+ * @yields each `AIHubEvent` decoded from the byte stream, in emission order.
+ */
+export async function* parseSseStream(
+  body: ReadableStream<Uint8Array>,
+): AsyncIterable<AIHubEvent> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        // Flush any trailing block (server didn't send the terminating
+        // blank line). Defensive — the server always closes cleanly.
+        const tail = buffer.trim();
+        if (tail.length > 0) {
+          const event = parseEventBlock(tail);
+          if (event) yield event;
+        }
+        return;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // Event blocks are separated by a blank line. Handle both `\n\n`
+      // (what our server emits) and `\r\n\r\n` (what some intermediaries
+      // and the spec officially require) for resilience.
+      // eslint-disable-next-line no-constant-condition
+      while (true) {
+        const sep = findBlockSeparator(buffer);
+        if (sep === null) break;
+        const block = buffer.slice(0, sep.end);
+        buffer = buffer.slice(sep.next);
+        const event = parseEventBlock(block);
+        if (event) yield event;
+      }
+    }
+  } finally {
+    // Release the reader so the stream can be cancelled cleanly upstream.
+    try {
+      reader.releaseLock();
+    } catch {
+      /* already released */
+    }
+  }
+}
+
+/**
+ * Indices identifying an SSE event-block separator inside the buffer.
+ * `end` is the exclusive end of the block content; `next` is where the
+ * next block's content starts.
+ */
+interface SeparatorIndex {
+  /** Exclusive end-of-block index (everything before this is one event). */
+  end: number;
+  /** Start-of-next-block index (the parser slices the buffer here). */
+  next: number;
+}
+
+/** Standalone helper so `parseSseStream` stays readable. */
+function findBlockSeparator(s: string): SeparatorIndex | null {
+  const lf = s.indexOf("\n\n");
+  const crlf = s.indexOf("\r\n\r\n");
+  if (lf === -1 && crlf === -1) return null;
+  if (crlf !== -1 && (lf === -1 || crlf < lf)) {
+    return { end: crlf, next: crlf + 4 };
+  }
+  return { end: lf, next: lf + 2 };
+}
+
+/**
+ * Parses one event block (lines up to but not including the blank-line
+ * separator) into an `AIHubEvent`, or returns null if the block is a
+ * comment / malformed.
+ *
+ * @param block - the raw text of one block.
+ * @returns the parsed event, or null on skip.
+ */
+function parseEventBlock(block: string): AIHubEvent | null {
+  let eventName: string | null = null;
+  // Per the SSE spec, multi-line `data:` payloads are concatenated with
+  // newlines. Our server only ever emits single-line JSON, but accept
+  // multi-line payloads defensively.
+  const dataLines: string[] = [];
+
+  for (const line of block.split(/\r?\n/)) {
+    if (line.length === 0) continue;
+    if (line.startsWith(":")) continue; // SSE comment — skip
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const field = line.slice(0, colonIdx);
+    // Per the spec, a single space after the colon is stripped if present.
+    const valueStart = line.charAt(colonIdx + 1) === " " ? colonIdx + 2 : colonIdx + 1;
+    const value = line.slice(valueStart);
+
+    if (field === "event") eventName = value;
+    else if (field === "data") dataLines.push(value);
+    // id / retry fields are unused — ignore them.
+  }
+
+  if (!eventName || dataLines.length === 0) return null;
+
+  let payload: { seq: number; data?: unknown; state: { status: string; phase: string | null } };
+  try {
+    payload = JSON.parse(dataLines.join("\n")) as typeof payload;
+  } catch {
+    return null;
+  }
+  if (
+    typeof payload !== "object" ||
+    payload === null ||
+    typeof payload.seq !== "number" ||
+    typeof payload.state !== "object" ||
+    payload.state === null
+  ) {
+    return null;
+  }
+
+  // The shape on the wire mirrors `AIHubEvent` exactly minus the discriminator
+  // (which lives on the `event:` line, not in the JSON payload). Re-attach it
+  // here. `heartbeat` events carry no `data` field per the union.
+  return {
+    event: eventName,
+    seq: payload.seq,
+    state: payload.state,
+    ...(payload.data !== undefined ? { data: payload.data } : {}),
+  } as AIHubEvent;
+}

package/src/client/tokenStorage.ts

@@ -0,0 +1,131 @@
+/**
+ * Token storage adapters for `AIHubClient`.
+ *
+ * Three modes per §7.2 (the `tokenStorage` prop on `<AIHubProvider>`):
+ *
+ * - `"localStorage"` (default) — persists across tabs and browser restarts.
+ * - `"sessionStorage"` — persists across reloads within a tab; cleared on
+ *   tab close. Useful for embeds where the embedding page is itself
+ *   ephemeral.
+ * - `"memory"` — never persisted. Useful for tests, server-side rendering,
+ *   and embedding contexts where the host page provides its own persistence
+ *   strategy.
+ *
+ * The adapter is a tiny three-method interface so future modes (e.g. an
+ * IndexedDB-backed one for very-large session counts, or a host-supplied
+ * one for embedding contexts that want to share storage with the parent
+ * page) are an additive change.
+ *
+ * @see SPECIFICATIONS.md §7.2 — `<AIHubProvider>` props
+ * @see SPECIFICATIONS.md §6.7 — token lifetimes
+ */
+
+/**
+ * The storage adapter `AIHubClient` reads/writes the session JWT through.
+ * The contract is intentionally minimal — three pure methods, no async.
+ */
+export interface TokenStorage {
+  /** Returns the stored token, or `null` if none is set. */
+  get(): string | null;
+  /** Replaces any existing token. */
+  set(token: string): void;
+  /** Removes the stored token (idempotent — no-op when none was set). */
+  clear(): void;
+}
+
+/** Identifier strings for the three built-in adapters. */
+export type TokenStorageMode = "localStorage" | "sessionStorage" | "memory";
+
+const STORAGE_KEY = "data-club-ai-hub:token";
+
+/**
+ * Builds an in-memory token storage. Used by the `"memory"` mode and as a
+ * fallback when the browser's storage APIs throw (Safari private mode, etc.).
+ *
+ * @returns a fresh in-memory storage adapter.
+ */
+export function createMemoryTokenStorage(): TokenStorage {
+  let value: string | null = null;
+  return {
+    get: () => value,
+    set: (token) => {
+      value = token;
+    },
+    clear: () => {
+      value = null;
+    },
+  };
+}
+
+/**
+ * Builds a `Storage`-backed adapter (localStorage or sessionStorage).
+ *
+ * Falls back to an in-memory adapter if the underlying storage throws on
+ * the first call (Safari private mode, embedded iframe with storage
+ * blocked, etc.) — we'd rather degrade silently than break the auth flow.
+ *
+ * @param storage - the underlying `Storage` instance.
+ * @returns an adapter that reads/writes through the given storage.
+ */
+function createWebStorageTokenStorage(storage: Storage): TokenStorage {
+  try {
+    storage.getItem(STORAGE_KEY);
+  } catch {
+    return createMemoryTokenStorage();
+  }
+  return {
+    get: () => {
+      try {
+        return storage.getItem(STORAGE_KEY);
+      } catch {
+        return null;
+      }
+    },
+    set: (token) => {
+      try {
+        storage.setItem(STORAGE_KEY, token);
+      } catch {
+        /* ignore */
+      }
+    },
+    clear: () => {
+      try {
+        storage.removeItem(STORAGE_KEY);
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
+
+/**
+ * Resolves a `TokenStorageMode` (or a custom `TokenStorage` instance) into
+ * a concrete adapter.
+ *
+ * In non-browser environments (SSR, Node tests without jsdom), the
+ * `"localStorage"` / `"sessionStorage"` modes silently fall back to
+ * `"memory"` — this is what keeps SSR-rendering an `<AIHubProvider>` from
+ * crashing on missing globals.
+ *
+ * @param mode - either one of the three mode strings or a custom adapter.
+ * @returns the concrete adapter.
+ */
+export function resolveTokenStorage(
+  mode: TokenStorageMode | TokenStorage,
+): TokenStorage {
+  if (typeof mode === "object") return mode;
+  if (mode === "memory") return createMemoryTokenStorage();
+  const globalRef = typeof globalThis !== "undefined" ? globalThis : undefined;
+  const win =
+    globalRef && "window" in globalRef
+      ? (globalRef as { window?: Window }).window
+      : undefined;
+  if (!win) return createMemoryTokenStorage();
+  if (mode === "localStorage" && win.localStorage) {
+    return createWebStorageTokenStorage(win.localStorage);
+  }
+  if (mode === "sessionStorage" && win.sessionStorage) {
+    return createWebStorageTokenStorage(win.sessionStorage);
+  }
+  return createMemoryTokenStorage();
+}

package/src/components/AgentsPicker/index.tsx

@@ -0,0 +1,147 @@
+/**
+ * `<AgentsPicker />` — the post-login landing view.
+ *
+ * Renders one card per non-archived ai-hub agent the caller has access to,
+ * with the caller-scoped `session_count` baked into the subtitle so a
+ * single round-trip populates the entire picker (§6.3.3). Clicking a card
+ * calls `useAIHub().setActiveAgent(id)` — the parent shell then renders
+ * the chat layout for that agent.
+ *
+ * Auto-skip behaviour (consumed by `ChatShell` above): the picker is
+ * skipped entirely when `showAgentsPicker={false}` *or* when the
+ * deployment ships exactly one agent — those skips happen at the
+ * `ChatShell` level so this component stays a pure listing view.
+ *
+ * Exported under the `AIHub.AgentsPicker` Tier-3 primitive.
+ *
+ * @see SPECIFICATIONS.md §7.1 — exports
+ * @see SPECIFICATIONS.md §6.3.3 — `/agents`
+ * @see ui-sketches/03-chat.md — visual contract for the picker
+ */
+
+import { type ReactNode } from "react";
+
+import { resolveAIHubTexts, type AIHubTexts, type DeepPartial } from "../../auth/texts.js";
+import { useAIHub } from "../../context/useAIHub.js";
+
+/**
+ * BEM class names emitted by `<AgentsPicker />`. Per-customer wrappers
+ * pass a partial of this map via the `classNames` prop to override
+ * individual names for utility-CSS frameworks.
+ */
+export interface AgentsPickerClassNames {
+  /** Outer wrapper (centers the picker, scrolls when too tall). */
+  root: string;
+  /** Page heading at the top. */
+  heading: string;
+  /** Loading line shown while `/agents` is in flight. */
+  loading: string;
+  /** Error banner shown when `/agents` fails. */
+  error: string;
+  /** Empty-state container. */
+  empty: string;
+  /** Empty-state heading. */
+  emptyHeading: string;
+  /** Empty-state body. */
+  emptyBody: string;
+  /** Card grid wrapper. */
+  grid: string;
+  /** A single agent card (the clickable tile). */
+  card: string;
+  /** Card display name. */
+  cardName: string;
+  /** Card subtitle line (session count). */
+  cardSubtitle: string;
+}
+
+/**
+ * Default BEM class names. Stable, kebab-case, scoped under
+ * `data-club-ai-hub__agents-picker`. Wrappers override individual entries
+ * via the `classNames` prop.
+ */
+const DEFAULT_CLASS_NAMES: AgentsPickerClassNames = Object.freeze({
+  root: "data-club-ai-hub__agents-picker",
+  heading: "data-club-ai-hub__agents-picker__heading",
+  loading: "data-club-ai-hub__agents-picker__loading",
+  error: "data-club-ai-hub__agents-picker__error",
+  empty: "data-club-ai-hub__agents-picker__empty",
+  emptyHeading: "data-club-ai-hub__agents-picker__empty-heading",
+  emptyBody: "data-club-ai-hub__agents-picker__empty-body",
+  grid: "data-club-ai-hub__agents-picker__grid",
+  card: "data-club-ai-hub__agent-card",
+  cardName: "data-club-ai-hub__agent-card__name",
+  cardSubtitle: "data-club-ai-hub__agent-card__subtitle",
+}) as AgentsPickerClassNames;
+
+/**
+ * Props for `<AgentsPicker />`.
+ */
+export interface AgentsPickerProps {
+  /** Extra class merged onto the root wrapper. */
+  className?: string;
+  /** Per-element class-name overrides. */
+  classNames?: Partial<AgentsPickerClassNames>;
+  /** Wrapper-supplied i18n. */
+  texts?: DeepPartial<AIHubTexts>;
+}
+
+/**
+ * Renders the agents picker.
+ *
+ * @param props - see `AgentsPickerProps`.
+ * @returns the rendered picker.
+ */
+export function AgentsPicker(props: AgentsPickerProps): ReactNode {
+  const { agents, agentsLoading, setActiveAgent } = useAIHub();
+  const texts = resolveAIHubTexts(props.texts);
+  const cls = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+  const rootClass = props.className
+    ? `${cls.root} ${props.className}`
+    : cls.root;
+
+  return (
+    <div className={rootClass} data-testid="agents-picker">
+      <h1 className={cls.heading}>{texts.chat.agentsPickerHeading}</h1>
+      {agentsLoading && agents.length === 0 ? (
+        <p className={cls.loading} data-testid="agents-picker-loading">
+          {texts.chat.agentsPickerLoading}
+        </p>
+      ) : null}
+      {!agentsLoading && agents.length === 0 ? (
+        <div className={cls.empty} data-testid="agents-picker-empty">
+          <h2 className={cls.emptyHeading}>
+            {texts.chat.agentsPickerEmptyHeading}
+          </h2>
+          <p className={cls.emptyBody}>{texts.chat.agentsPickerEmptyBody}</p>
+        </div>
+      ) : null}
+      {agents.length > 0 ? (
+        <div className={cls.grid} role="list">
+          {agents.map((agent) => {
+            const subtitle =
+              agent.session_count === 0
+                ? texts.chat.agentCardNoSessionsSubtitle
+                : texts.chat.agentCardSessionsSubtitle.replace(
+                    "{count}",
+                    String(agent.session_count),
+                  );
+            return (
+              <button
+                key={agent.id}
+                type="button"
+                role="listitem"
+                className={cls.card}
+                data-testid="agent-card"
+                data-agent-id={agent.id}
+                onClick={() => setActiveAgent(agent.id)}
+              >
+                <span className={cls.cardName}>{agent.display_name}</span>
+                <span className={cls.cardSubtitle}>{subtitle}</span>
+              </button>
+            );
+          })}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/AuthGate/index.tsx

@@ -0,0 +1,132 @@
+/**
+ * `AIHub.AuthGate` — the auth-state router.
+ *
+ * Reads `useAIHubAuth()` and renders:
+ *
+ * - `<DataClubAIHubLogin />` when no user is present.
+ * - `<DataClubAIHubChangePassword variant="forced" />` when a user is
+ *   present but `mustChangePassword === true`.
+ * - `children` (the chat / admin / whatever) otherwise.
+ *
+ * While the provider is still hydrating from a stored token (`hydrating ===
+ * true`) the gate renders nothing — preventing a one-frame flash of the
+ * login card before the cached session resolves.
+ *
+ * Tier 3 wrappers compose this primitive as the second layer (after
+ * `AIHub.Provider`) so the auth UX is handled automatically; Tier 1 / 2
+ * wrappers get the same behavior for free via `<DataClubAIHub />`.
+ *
+ * @see SPECIFICATIONS.md §7.1   — exports
+ * @see SPECIFICATIONS.md §7.2.1 — auth-owned-by-library policy
+ * @see SPECIFICATIONS.md §7.9   — Tier-3 composition example
+ * @see ui-sketches/01-login.md
+ * @see ui-sketches/02-change-password.md
+ */
+
+import { type ReactNode } from "react";
+
+import { useAIHubAuth } from "../../context/useAIHubAuth.js";
+import type { AIHubTexts, DeepPartial } from "../../auth/texts.js";
+import {
+  DataClubAIHubLogin,
+  type AIHubLoginClassNames,
+} from "../DataClubAIHubLogin/index.js";
+import {
+  DataClubAIHubChangePassword,
+  type AIHubChangePasswordClassNames,
+} from "../ChangePassword/index.js";
+
+/**
+ * Props for `AIHub.AuthGate`. The branding / i18n props mirror
+ * `<DataClubAIHub />` — Tier 3 wrappers pass them through here so the
+ * auto-rendered Login + ChangePassword screens get branded without the
+ * wrapper having to render those screens manually.
+ */
+export interface AuthGateProps {
+  /**
+   * Rendered when the user is authenticated and is not in the forced
+   * change-password state. The wrapper is responsible for the actual
+   * chat / admin tree.
+   */
+  children: ReactNode;
+  /**
+   * Title text on the login card. Forwarded to `<DataClubAIHubLogin />`.
+   * Defaults to `"ai-hub"`.
+   */
+  productName?: string;
+  /**
+   * Placeholder shown inside the username input on the login card.
+   * Forwarded to `<DataClubAIHubLogin />`. Defaults to empty.
+   */
+  usernamePlaceholder?: string;
+  /**
+   * Wrapper-supplied i18n applied to both auto-rendered auth screens.
+   */
+  texts?: DeepPartial<AIHubTexts>;
+  /** Per-element class overrides forwarded to `<DataClubAIHubLogin />`. */
+  loginClassNames?: Partial<AIHubLoginClassNames>;
+  /**
+   * Per-element class overrides forwarded to
+   * `<DataClubAIHubChangePassword />`.
+   */
+  changePasswordClassNames?: Partial<AIHubChangePasswordClassNames>;
+  /**
+   * Optional `className` forwarded onto the login root.
+   */
+  loginClassName?: string;
+  /**
+   * Optional `className` forwarded onto the change-password root.
+   */
+  changePasswordClassName?: string;
+}
+
+/**
+ * Renders the right screen for the current auth state.
+ *
+ * @param props - see `AuthGateProps`.
+ * @returns the rendered subtree.
+ */
+export function AuthGate(props: AuthGateProps): ReactNode {
+  const auth = useAIHubAuth();
+
+  if (auth.hydrating) {
+    // Render nothing — we don't know yet whether the stored token is valid.
+    // FOUC-of-login-card avoidance.
+    return null;
+  }
+
+  if (!auth.user) {
+    return (
+      <DataClubAIHubLogin
+        {...(props.productName !== undefined ? { productName: props.productName } : {})}
+        {...(props.usernamePlaceholder !== undefined
+          ? { usernamePlaceholder: props.usernamePlaceholder }
+          : {})}
+        {...(props.texts !== undefined ? { texts: props.texts } : {})}
+        {...(props.loginClassNames !== undefined
+          ? { classNames: props.loginClassNames }
+          : {})}
+        {...(props.loginClassName !== undefined
+          ? { className: props.loginClassName }
+          : {})}
+      />
+    );
+  }
+
+  if (auth.mustChangePassword) {
+    return (
+      <DataClubAIHubChangePassword
+        variant="forced"
+        {...(props.texts !== undefined ? { texts: props.texts } : {})}
+        {...(props.changePasswordClassNames !== undefined
+          ? { classNames: props.changePasswordClassNames }
+          : {})}
+        {...(props.changePasswordClassName !== undefined
+          ? { className: props.changePasswordClassName }
+          : {})}
+      />
+    );
+  }
+
+  return <>{props.children}</>;
+}